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
| Environment | Base URL |
|---|---|
| Sandbox | https://api-sandbox.aiprise.com/api/v1/token-sharing |
| Production | https://api.aiprise.com/api/v1/token-sharing |
Send your API key in the X-API-KEY header, the same as other AiPrise APIs.
Endpoints
| Endpoint | Used by | What it does | Rate limit |
|---|---|---|---|
POST /export | Donor | Share one approved record with a Recipient now | 60 per minute |
GET /tokens?side=DONOR | Donor | List the tokens you have shared | 120 per minute |
GET /tokens?side=RECIPIENT | Recipient | List the tokens shared with you | 120 per minute |
GET /tokens/{token_id}/preview | Donor or Recipient | Get a short summary of one token | 120 per minute |
POST /tokens/{token_id}/import | Recipient | Import a token into your account | 60 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.
| Field | Type | Description | Donor | Recipient |
|---|---|---|---|---|
id | string | Token ID | Yes | Yes |
donor_company_id | string | Donor's AiPrise company ID | Yes | Yes |
recipient_company_id | string | Recipient's AiPrise company ID | Yes | Yes |
contract_id | string | The connection the token was shared under | Yes | Yes |
agreement_id | string | The agreement the token was shared under | Yes | Yes |
agreement_version | integer | Agreement version at the time of sharing | Yes | Yes |
entity_type | string | BUSINESS_PROFILE, USER_PROFILE or USER_SESSION | Yes | Yes |
entity_name_as_per_donor | string | Business name or person's full name at the time of sharing | Yes | Yes |
entity_id_as_per_donor | string | The Donor's profile or session ID | Yes | No |
entity_id_as_per_recipient | string | The Recipient's own profile or session ID, set after import | No | Yes |
state | string | Token state, see below | Yes | Yes |
created_at | integer | Unix milliseconds | Yes | Yes |
updated_at | integer | Unix milliseconds | Yes | Yes |
Token states
| State | Meaning | Seen by |
|---|---|---|
READY_TO_BE_EXPORTED | Created after approval, waiting out the settle window | Donor |
READY_TO_BE_IMPORTED | Sent to the Recipient and waiting for import | Both |
IMPORTING | An import is running | Both |
IMPORTED | The Recipient's copy has been created | Both |
IMPORT_FAILED | The import could not complete. It is not retried. | Both |
TOKEN_EXPORT_FAILED | The token could not be sent. Contact AiPrise support. | Donor |
See Verification Tokens for the full lifecycle.
Errors
| Status | When |
|---|---|
400 | The request is missing a field or has an invalid value. The response message says which. |
401 | The API key is missing or invalid. |
404 | The 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. |
429 | You went over the rate limit for the endpoint. |
Next steps
Updated about 20 hours ago
Did this page help you?
