API Integration

Automate Token Sharing with the AiPrise API.

You can run Token Sharing entirely from the AiPrise Dashboard. Use the API when you want your own systems to share records, react to new tokens, or import them automatically.

  • Donors use the API to share a record on demand and track what they have shared. See Donor Integration.
  • Recipients use the API and webhooks to learn about new tokens, preview them, import them and read the imported record. See Recipient Integration.

Before you start

  • The connection and agreement between the two companies are set up in the Dashboard. See Get Started.
  • The agreement is live. Only customers approved while an agreement is live are shared.
  • You have an API key for your company. See Managing API Keys.

Token Sharing in the sandbox environment is coming soon. Contact the AiPrise team to plan an end-to-end test.

Base URL and authentication

EnvironmentBase URL
Sandboxhttps://api-sandbox.aiprise.com/api/v1/token-sharing
Productionhttps://api.aiprise.com/api/v1/token-sharing

Send your API key in the X-API-KEY header, the same as other AiPrise APIs.

Endpoints

EndpointUsed byWhat it doesRate limit
POST /exportDonorShare one approved record with a Recipient now60 per minute
GET /tokens?side=DONORDonorList the tokens you have shared120 per minute
GET /tokens?side=RECIPIENTRecipientList the tokens shared with you120 per minute
GET /tokens/{token_id}/previewDonor or RecipientGet a short summary of one token120 per minute
POST /tokens/{token_id}/importRecipientImport a token into your account60 per minute

The token object

Every endpoint and webhook returns tokens in the same shape. Each side sees its own entity ID and never the other side's.

FieldTypeDescriptionDonorRecipient
idstringToken IDYesYes
donor_company_idstringDonor's AiPrise company IDYesYes
recipient_company_idstringRecipient's AiPrise company IDYesYes
contract_idstringThe connection the token was shared underYesYes
agreement_idstringThe agreement the token was shared underYesYes
agreement_versionintegerAgreement version at the time of sharingYesYes
entity_typestringBUSINESS_PROFILE, USER_PROFILE or USER_SESSIONYesYes
entity_name_as_per_donorstringBusiness name or person's full name at the time of sharingYesYes
entity_id_as_per_donorstringThe Donor's profile or session IDYesNo
entity_id_as_per_recipientstringThe Recipient's own profile or session ID, set after importNoYes
statestringToken state, see belowYesYes
created_atintegerUnix millisecondsYesYes
updated_atintegerUnix millisecondsYesYes

Token states

StateMeaningSeen by
READY_TO_BE_EXPORTEDCreated after approval, waiting out the settle windowDonor
READY_TO_BE_IMPORTEDSent to the Recipient and waiting for importBoth
IMPORTINGAn import is runningBoth
IMPORTEDThe Recipient's copy has been createdBoth
IMPORT_FAILEDThe import could not complete. It is not retried.Both
TOKEN_EXPORT_FAILEDThe token could not be sent. Contact AiPrise support.Donor

See Verification Tokens for the full lifecycle.

Errors

StatusWhen
400The request is missing a field or has an invalid value. The response message says which.
401The API key is missing or invalid.
404The token, record or contract does not exist, or does not belong to your company. AiPrise returns the same 404 in both cases, so an ID never reveals another company's data.
429You went over the rate limit for the endpoint.

Next steps


Did this page help you?