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_IMPORTEDto 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_IMPORTEDand thenTOKEN_IMPORTEDorTOKEN_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_type | entity_id_as_per_recipient is your | Read it with |
|---|---|---|
BUSINESS_PROFILE | business_profile_id | Get Business Profile |
USER_PROFILE | user_profile_id | Get user profile |
USER_SESSION | verification_session_id | Get 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.
| Reason | What it means |
|---|---|
NO_TEMPLATE | Your agreement has no template for this record type. |
TEMPLATE_NOT_USABLE | The template on your agreement is archived or does not belong to your company. |
MISSING_INPUTS | Your template requires fields the shared record does not have. |
INPUTS_REJECTED | The shared data did not pass your template's validation. |
NOT_ELIGIBLE | The Donor's record was no longer approved at the time of import. |
IMPORTER_NOT_AVAILABLE | This record type cannot be imported yet. |
RECIPIENT_NOT_PERMITTED | Your account is missing a feature this record type needs. |
INTERNAL_ERROR | Something 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.
Updated about 20 hours ago
