Receive a shared record

If you buy leads, this is the whole of your integration. One authenticated request per lead, and the consent evidence is in your account.

You never install the SDK. The company that ran the website captured the record; your side is taking delivery of it.

What you were given

A share URL, alongside the lead itself. It looks like this:

https://api-next.expressconsent.com/v1/shares/xYz7Qw...

The token at the end is the authority to take that record. Whoever holds it can, so treat it like a password in your lead payloads and your logs.

1. Get an API key

Create one under Organization → API keys in the dashboard. The secret is shown once. A key identifies your organization and nothing finer, so it belongs on your server. See API conventions.

2. Post to the share URL

curl -sS -X POST -H "X-API-Key: $EC_API_KEY" \
  "https://api-next.expressconsent.com/v1/shares/xYz7Qw..."

{
  "ok": true,
  "data": {
    "claimed": true,
    "alreadyClaimed": false,
    "cdrId": "cdr_abc123",
    "domainId": "example.com",
    "shareEventId": "se_9f2b..."
  },
  "requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
}

Store cdrId on the lead. Sent with no body, this also makes you the payer for the record and gives you download access, unless the seller had already paid for it, in which case their access passes to you at no charge. Access and collection covers who ends up billed.

Repeating the request is safe. It is idempotent per organization and never charges twice, so a retry after a timeout is the correct response rather than a risk. A repeat answers alreadyClaimed: true with an empty shareEventId, so store cdrId rather than shareEventId.

The body accepts collect and acceptance and nothing else. An unrecognized field is a 400, which is deliberate: a misspelled acceptance must not quietly mean "no requirements".

Refusing records you do not want

You can attach requirements to the request and have a record refused before it reaches your account. A record that fails is not saved and not billed.

curl -sS -X POST -H "X-API-Key: $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acceptance": {"schemaVersion": 1, "disclosure": {"requireUserSubmission": true}}}' \
  "https://api-next.expressconsent.com/v1/shares/xYz7Qw..."

schemaVersion is required. An acceptance object without it is refused with 400 INVALID_ARGUMENT rather than applied as an empty policy.

Every available requirement (disclosure text matching, checkbox state, record age, matching the phone number you were sold against the one on the record) is on acceptance criteria.

When a seller's records start failing, error.details.failures[] names each rule that did not pass, which is the thing to forward to them. Requirements that could not be evaluated at all refuse the record too, usually because nothing was detected as a submission, which is worth understanding before you read a batch of failures as bad faith.

Next