# 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](https://app.expressconsent.com/docs/reference/api).

## 2. Post to the share URL

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

```json
{
  "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](https://app.expressconsent.com/docs/concepts/access) 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.

```bash
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](https://app.expressconsent.com/docs/reference/api/acceptance).

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

- [Acceptance criteria](https://app.expressconsent.com/docs/reference/api/acceptance): Refuse a shared record that does not meet your requirements, before it reaches your account.
- [Access and collection](https://app.expressconsent.com/docs/concepts/access): Which organization can download a CDR, which one is charged for it, and how access moves when evidence is shared.