# 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://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. This request also collects the record: you are charged for it and get download access in the same call. If your organization already had access to the record, you are not charged again. [Access and collection](https://expressconsent.com/docs/concepts/access) covers who ends up billed.

Repeating the request is safe. It is idempotent per organization, including when your organization already holds the record through another token or sender, 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 `acceptance` and nothing else, apart from an optional `collect`, which must be `true` if sent. 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, "requireConsent": {"mechanisms": ["checkbox"]}}}' \
  "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 (how the person consented, record age, matching the phone number you were sold against the one on the record) is on [acceptance criteria](https://expressconsent.com/docs/reference/api/acceptance).

When a seller's records start failing, `error.details.failures[]` names each requirement that did not pass, which is the thing to forward to them. A requirement that could not be evaluated refuses the record too. That usually means no submission was detected on the seller's form, which is a fix on their side.

## Next

- [Acceptance criteria](https://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://expressconsent.com/docs/concepts/access): Which organization can download a CDR, which one is charged for it, and what happens when evidence is shared.
