API reference
Get a fresh ID-check link
The ID-check link for an account you created — when the first one expired, the creator closed it, or the check was declined and they may try again.
View as MarkdownUpdated Oct 17, 2026
POST
/api/external/v1/accounts/{id}/kyc-sessionalso served at /api/external/accounts/{id}/kyc-sessionNewThe ID-check link for an account you created — when the first one expired, the creator closed it, or the check was declined and they may try again.
A link younger than 24 hours is reused unless you pass a new kycReturnUrl.
Authentication
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The accountId. |
Request body
Content type: application/json — Optional.
| Name | Type | Required | Description |
|---|---|---|---|
kycReturnUrl | string | Optional | https URL to return to; we append ?kyc=<status>.Format: uri |
acceptedFromIp | string | Optional | The creator’s browser IP, when you have it. |
acceptedUserAgent | string | Optional | The creator’s browser user agent. |
New link with a return URL
{
"kycReturnUrl": "https://crm.example.com/onboarding/done"
}Responses
200The link.
| Name | Type | Description |
|---|---|---|
kycUrl | string | Redirect the creator here. Format: uri |
kycExpiresAt | string | Reused until then. Format: date-time |
reused | boolean | True when an open session was returned. |
Example response
{
"kycUrl": "https://verify.didit.me/session/…",
"kycExpiresAt": "2026-10-18T16:00:00.000Z",
"reused": false
}Errors
| Status | Body | When |
|---|---|---|
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 403 | {"error":"This endpoint needs a key bound to an approved app.","code":"app_key_required"} | A Personal key was used. |
| 403 | {"error":"Use the app owner's key for this endpoint.","code":"owner_key_required"} | The key was minted by a creator for themselves. App-level calls need a key held by your app owner: their own, or one their agency minted for its personas or managed creators. |
| 404 | {"error":"Account not found"} | No such account, or another app created it. |
| 409 | {"error":"The ID check is already done.","code":"already_verified"} | Approved (or being finalised) — nothing to do. |
| 503 | {"error":"The ID check is unavailable right now. Try again later.","code":"kyc_unavailable"} | The verification provider is down. |
| 400 | {"error":"This endpoint acts as the key’s own account or app — call it without /creators/{creatorId}.","code":"creator_scope_not_allowed"} | Called under /api/external/v1/creators/{creatorId}/ — this endpoint always acts as the key’s own account, agency or app. |
| 403 | {"error":"This app does not have the onboarding API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"onboarding"} | Your app has the Creator onboarding [API category](/developers/concepts/api-categories) switched off (the default for new apps). |
Rate limiting
Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.
Code samples
curl -X POST "https://www.dropfans.io/api/external/v1/accounts/$ID/kyc-session" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kycReturnUrl": "https://crm.example.com/onboarding/done"
}'const id = '…'; // from an earlier response
const res = await fetch(`https://www.dropfans.io/api/external/v1/accounts/${id}/kyc-session`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"kycReturnUrl": "https://crm.example.com/onboarding/done"
}),
});
console.log(await res.json());import os
import requests
id = "…" # from an earlier response
res = requests.post(
f"https://www.dropfans.io/api/external/v1/accounts/{id}/kyc-session",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"kycReturnUrl": "https://crm.example.com/onboarding/done",
},
)
print(res.json())Questions? support@dropfans.io