Donor Integration

Share approved records with a partner and track them through the API.

As a Donor, you share customers you have already verified with a connected Recipient.

How sharing starts

There are two ways a record gets shared:

  1. Automatically on approval. When you approve a business profile, user profile or user verification session that matches a live agreement, AiPrise creates a token. After a short settle window, AiPrise checks eligibility again and sends the token to the Recipient. You don't need to call any API for this.
  2. On demand with the export API. Call Export a profile or case to share a specific record right away, for example a customer you approved before the agreement went live.

The settle window protects you from a quick reversal: if you change an approval within the window, the record is not shared.

Share a record on demand

Call POST /token-sharing/export with the record and the connection to share it on.

curl --request POST \
  --url https://api.aiprise.com/api/v1/token-sharing/export \
  --header 'X-API-KEY: <your API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "entity_type": "BUSINESS_PROFILE",
    "entity_id": "<your business_profile_id>",
    "contract_id": "<contract_id of the connection>"
  }'
FieldDescription
entity_typeBUSINESS_PROFILE, USER_PROFILE or USER_SESSION
entity_idYour business_profile_id, user_profile_id or verification_session_id
contract_idThe ID of your connection with the Recipient. You must be the Donor on it. Contact the AiPrise team if you don't have it.

The record goes through the same checks as an automatic share: the agreement's eligibility rules, maximum verification age and consent. The response is always 200 for a valid request. Read export_state:

export_stateWhat happened
READY_TO_BE_EXPORTEDA token was created and is being sent. It reaches the Recipient within seconds.
TOKEN_EXPORT_FAILEDA token was created but could not be sent. Contact AiPrise support.
TOKEN_NOT_CREATEDNo token was created. Either no live agreement on this connection matches the record, or the record was already shared on this connection.

A record is shared at most once per connection. To find an existing token, list your exported tokens.

Track what you have shared

  • List: List exported tokens returns your tokens newest first. Filter by state, for example state=IMPORT_FAILED.
  • Preview: Preview a token returns the token's state, both company names, the agreement and what was shared.
  • Webhooks: you can receive TOKEN_IMPORTED and TOKEN_IMPORT_FAILED when the Recipient imports. See Token Sharing Webhooks.

What the Donor sees

  • You see your own entity ID (entity_id_as_per_donor) on every token. You never see the Recipient's entity ID.
  • When an import fails, you see the failure reason code only. The details can describe the Recipient's own setup, so they are shown to the Recipient only.

Did this page help you?