Recipient Integration

Find, preview and import shared records, then read them with the standard APIs.

As a Recipient, you receive records that a connected Donor has already verified. Each record arrives as a token that you import into your own account.

1. Know when a token arrives

  • Webhook: AiPrise sends TOKEN_READY_TO_BE_IMPORTED to your webhook URL when a token is sent to you. See Token Sharing Webhooks.
  • Polling: call List received tokens with state=READY_TO_BE_IMPORTED. Use this to catch up if you missed a webhook.

You only see a token once it has been sent to you. The Donor's settle window is not visible to you.

2. Preview the token (optional)

Preview a token returns the Donor's name, the agreement, the record type, the business or person's name and, for businesses, the country. Use it to decide whether to import.

3. Import the token

Your agreement's import mode decides what happens next:

  • Automatic: AiPrise imports the token for you right away. You receive TOKEN_READY_TO_BE_IMPORTED and then TOKEN_IMPORTED or TOKEN_IMPORT_FAILED.
  • Manual: import it from the Dashboard, or call Import a token.
curl --request POST \
  --url https://api.aiprise.com/api/v1/token-sharing/tokens/<token_id>/import \
  --header 'X-API-KEY: <your API key>'

The import creates a new profile or session in your account from the shared data and runs the template set on your agreement. The response is the token after the import, with state set to IMPORTED or IMPORT_FAILED.

An import runs once. Only a token in READY_TO_BE_IMPORTED is imported. Calling import on a token in any other state returns it unchanged.

4. Read the imported record

After a successful import, token.entity_id_as_per_recipient is the ID of the new record in your account. Read it with the standard AiPrise APIs, the same as any other record:

entity_typeentity_id_as_per_recipient is yourRead it with
BUSINESS_PROFILEbusiness_profile_idGet Business Profile
USER_PROFILEuser_profile_idGet user profile
USER_SESSIONverification_session_idGet user verification result

To go the other way, from one of your records to the token it came from, call List received tokens with entity_id_as_per_recipient.

Handle a failed import

When an import fails, the token stays in IMPORT_FAILED and is not retried. The import response and the TOKEN_IMPORT_FAILED webhook include failure.reason and failure.details.

ReasonWhat it means
NO_TEMPLATEYour agreement has no template for this record type.
TEMPLATE_NOT_USABLEThe template on your agreement is archived or does not belong to your company.
MISSING_INPUTSYour template requires fields the shared record does not have.
INPUTS_REJECTEDThe shared data did not pass your template's validation.
NOT_ELIGIBLEThe Donor's record was no longer approved at the time of import.
IMPORTER_NOT_AVAILABLEThis record type cannot be imported yet.
RECIPIENT_NOT_PERMITTEDYour account is missing a feature this record type needs.
INTERNAL_ERRORSomething went wrong on AiPrise's side. Contact AiPrise support.

Records the failed import had already created in your account are kept and listed in failure.created_recipient_ids.


Did this page help you?