Skip to main content
POST
https://api.karmapay.xyz/v0
/
v0
/
end-users
/
:externalUserId
/
tos-link
curl -X POST 'https://api.karmapay.xyz/v0/end-users/user_123/tos-link' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectUri": "https://yourapp.com/onboarding/complete"
  }'

{
  "data": {
    "tosLinkId": "tos_link_12345",
    "tosLink": "https://dashboard.bridge.xyz/tos/accept/...",
    "tosStatus": "pending"
  }
}
Authentication: Business API Key
Generate a Terms of Service acceptance link for an end-user. This is step 2 of the Custom KYC flow. The user must accept Bridge’s Terms of Service before you can submit their KYC data. You can integrate this in two ways:
  1. iFrame Integration: Embed the ToS page directly in your application using an iframe and listen for the signed_agreement_id via postMessage
  2. Redirect Integration: Open the ToS page in a new window/tab and receive the signed_agreement_id via redirect URL

​
URL Parameters

​
externalUserId
string
required
Your internal user ID

​
Request Body

​
redirectUri
string
Optional URL to redirect the user after they accept the Terms of Service. The redirect will include a signed_agreement_id query parameter that you’ll need for the next step.

​
Response

​
data
object
curl -X POST 'https://api.karmapay.xyz/v0/end-users/user_123/tos-link' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectUri": "https://yourapp.com/onboarding/complete"
  }'

{
  "data": {
    "tosLinkId": "tos_link_12345",
    "tosLink": "https://dashboard.bridge.xyz/tos/accept/...",
    "tosStatus": "pending"
  }
}

​
Integration Methods

Embed the ToS page directly in your application using an iframe.
<iframe
  id="bridge-tos-iframe"
  src="[tosLink from API response]"
  title="Bridge Terms of Service"
  style="width: 100%; height: 600px; border: none;"
></iframe>

​
Step 2: Listen for signed_agreement_id via postMessage

Bridge will send a postMessage event when the user accepts the ToS. Listen for this event to capture the signed_agreement_id:
window.addEventListener('message', (event) => {
  // Security: Verify the origin is from Bridge
  if (event.origin !== 'https://dashboard.bridge.xyz') {
    console.warn('Unexpected origin:', event.origin);
    return;
  }

  // Check for signedAgreementId
  if (event.data && event.data.signedAgreementId) {
    const signedAgreementId = event.data.signedAgreementId;
    console.log('Received signed_agreement_id:', signedAgreementId);

    // Now submit KYC data with this ID
    submitKycData(signedAgreementId);
  }
});

​
Benefits:

  • Seamless user experience (no page navigation)
  • No need for redirectUri parameter
  • User stays within your application
  • Works great for SPAs and mobile apps
Next Steps: After receiving the signed_agreement_id (via either integration method), use it when calling POST /v0/end-users/:externalUserId/submit-kyc to submit KYC data.