---
title: "Consent"
description: "Read and record whether your organization may reach a contact by email, text or phone call."
canonical_url: "https://dealerme.com/docs/api/consent"
---

> Index of every page on this site: [llms.txt](https://dealerme.com/llms.txt)

The consent API stores what each contact has said about being reached by your organization, one record per contact per channel. Leads submitted on your dealerMe site with a consent checkbox are recorded here automatically, and you can read and write the same records from your own systems.

Consent endpoints are scoped to an organization. Send your API token and the organization's id with every request (see [Authentication](https://dealerme.com/docs/authentication)). The token's user must be a member of the organization, or the request returns `403`.

### Contact types

Every endpoint takes the channel as `{contactType}` in the path.

<table>
<thead>
  <tr>
    <th>
      Contact type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Contact value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        email
      </code>
    </td>
    
    <td>
      Email messages.
    </td>
    
    <td>
      An email address, up to 255 characters. Stored lowercased.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phone_sms
      </code>
    </td>
    
    <td>
      Text messages.
    </td>
    
    <td>
      A US, Canadian or Puerto Rican phone number. Stored in E.164 format.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phone_call
      </code>
    </td>
    
    <td>
      Phone calls.
    </td>
    
    <td>
      A US, Canadian or Puerto Rican phone number. Stored in E.164 format.
    </td>
  </tr>
</tbody>
</table>

Contact values are normalized before they're stored or looked up, so `+1 (555) 123-4567` and `5551234567` are the same contact, as are `Jane@Example.com` and `jane@example.com`.

### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        contact_value
      </code>
    </td>
    
    <td>
      String
    </td>
    
    <td>
      The email address or phone number, normalized.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        opt_in
      </code>
    </td>
    
    <td>
      Boolean
    </td>
    
    <td>
      <code>
        true
      </code>
      
       if the contact agreed to be reached on this channel, <code>
        false
      </code>
      
       if they opted out. <code>
        null
      </code>
      
       when there is no record for the contact.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        consent_timestamp
      </code>
    </td>
    
    <td>
      DateTime
    </td>
    
    <td>
      When the contact gave or withdrew consent (ISO 8601). <code>
        null
      </code>
      
       when there is no record for the contact.
    </td>
  </tr>
</tbody>
</table>

## Get a Consent

GET Request: `https://api.dealerme.com/v1/consent-management/{CONTACT_TYPE}/consent`

Returns the current consent for one contact. A contact with no record is not a `404`: the response has an `opt_in` and `consent_timestamp` of `null`.

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        contact_value
      </code>
    </td>
    
    <td>
      String
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       The email address or phone number to look up.
    </td>
  </tr>
</tbody>
</table>

<code-group>

```bash [CURL]
DEALERME_TOKEN="your API token"
DEALERME_ORG_ID="your organization id"

curl -G https://api.dealerme.com/v1/consent-management/phone_sms/consent \
  --data-urlencode "contact_value=+15555550123" \
  -H "Authorization: Bearer $DEALERME_TOKEN" \
  -H "X-DealerMe-Organization-Id: $DEALERME_ORG_ID" \
  -H 'Accept: application/json'
```

</code-group>

```json
{
  "contact_value": "+15555550123",
  "opt_in": true,
  "consent_timestamp": "2026-10-14T16:22:05+00:00"
}
```

## List Consents

GET Request: `https://api.dealerme.com/v1/consent-management/{CONTACT_TYPE}/consents`

Returns the consents on a channel whose `consent_timestamp` falls in a window, oldest first. Use it to keep your own copy in step with dealerMe.

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      Date
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       Start of the window. A date alone (<code>
        2026-10-01
      </code>
      
      ) starts at the beginning of that day; a datetime is used as given.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        to
      </code>
    </td>
    
    <td>
      Date
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       End of the window, on or after <code>
        from
      </code>
      
       and no more than 14 days after it. A date alone runs to the end of that day.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        page
      </code>
    </td>
    
    <td>
      Integer
    </td>
    
    <td>
      Page number, starting at <code>
        1
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        per_page
      </code>
    </td>
    
    <td>
      Integer
    </td>
    
    <td>
      Results per page. Defaults to <code>
        100
      </code>
      
      , maximum <code>
        500
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

<code-group>

```bash [CURL]
DEALERME_TOKEN="your API token"
DEALERME_ORG_ID="your organization id"

curl -G https://api.dealerme.com/v1/consent-management/email/consents \
  -d from=2026-10-01 \
  -d to=2026-10-14 \
  -d per_page=100 \
  -H "Authorization: Bearer $DEALERME_TOKEN" \
  -H "X-DealerMe-Organization-Id: $DEALERME_ORG_ID" \
  -H 'Accept: application/json'
```

</code-group>

```json
{
  "data": [
    {
      "contact_value": "jane@example.com",
      "opt_in": true,
      "consent_timestamp": "2026-10-03T14:08:51+00:00"
    },
    {
      "contact_value": "sam@example.com",
      "opt_in": false,
      "consent_timestamp": "2026-10-09T19:41:12+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 100,
    "total": 2,
    "last_page": 1
  }
}
```

## Record Consents

POST Request: `https://api.dealerme.com/v1/consent-management/{CONTACT_TYPE}/consents`

Records what up to 500 contacts said about being reached on a channel. Every entry is kept in the contact's consent history. A contact's current consent only changes when the entry's `consent_timestamp` is at least as recent as the one on record, so an older opt-in that arrives late can't undo a newer opt-out. If the same contact appears twice in one request with the same timestamp, the last entry wins.

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        contacts
      </code>
    </td>
    
    <td>
      Array
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       Between 1 and 500 contacts.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contacts.*.contact_value
      </code>
    </td>
    
    <td>
      String
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       The email address or phone number.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contacts.*.opt_in
      </code>
    </td>
    
    <td>
      Boolean
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       <code>
        true
      </code>
      
       to record consent, <code>
        false
      </code>
      
       to record an opt-out.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contacts.*.consent_timestamp
      </code>
    </td>
    
    <td>
      DateTime
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       When the contact gave or withdrew consent.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contacts.*.source
      </code>
    </td>
    
    <td>
      String
    </td>
    
    <td>
      Where the consent came from, up to 64 characters, such as <code>
        showroom
      </code>
      
       or <code>
        crm
      </code>
      
      . Defaults to <code>
        api
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contacts.*.disclosure
      </code>
    </td>
    
    <td>
      String
    </td>
    
    <td>
      The wording the contact agreed to, up to 10,000 characters.
    </td>
  </tr>
</tbody>
</table>

`source` and `disclosure` are dealerMe additions; they're stored with the contact's consent history.

<code-group>

```bash [CURL]
DEALERME_TOKEN="your API token"
DEALERME_ORG_ID="your organization id"

curl -X POST https://api.dealerme.com/v1/consent-management/phone_sms/consents \
  -H "Authorization: Bearer $DEALERME_TOKEN" \
  -H "X-DealerMe-Organization-Id: $DEALERME_ORG_ID" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      {
        "contact_value": "(555) 555-0123",
        "opt_in": true,
        "consent_timestamp": "2026-10-14T16:22:05Z",
        "source": "showroom",
        "disclosure": "I agree to receive text messages from Desert Motors."
      },
      {
        "contact_value": "555-555-0188",
        "opt_in": false,
        "consent_timestamp": "2026-10-14T17:03:40Z"
      }
    ]
  }'
```

</code-group>

A successful request returns an empty object.

```json
{}
```

## Sitemap

See the full [sitemap](https://dealerme.com/sitemap.md) for all pages.