# Verified Contacts

## List verified contacts

**get** `/v3/verified-contacts`

Lists contacts attached to the authenticated account's shared iMessage line.
Contacts start as `pending`; they become `verified` after the recipient sends
an inbound iMessage or SMS to the shared line.

### Returns

- `data: optional object { contacts, line }`

  - `contacts: array of object { created_at, phone_number, updated_at, 2 more }`

    - `created_at: string`

    - `phone_number: string`

      Contact phone number in E.164 format

    - `updated_at: string`

    - `verification_status: "pending" or "verified"`

      - `"pending"`

      - `"verified"`

    - `verified: boolean`

      Whether this contact has completed verification by messaging the shared line

  - `line: object { phone_number, type }`

    - `phone_number: string`

      Shared Sendblue line the contact must message to complete verification

    - `type: "shared"`

      - `"shared"`

### Example

```http
curl https://api.sendblue.co/v3/verified-contacts \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

#### Response

```json
{
  "data": {
    "contacts": [
      {
        "created_at": "2026-08-12T18:32:12.000Z",
        "phone_number": "+12125550199",
        "updated_at": "2026-08-12T18:32:12.000Z",
        "verification_status": "pending",
        "verified": false
      }
    ],
    "line": {
      "phone_number": "+12125550101",
      "type": "shared"
    }
  }
}
```

## Create a pending verified contact

**post** `/v3/verified-contacts`

Creates or returns a verified-contact route for the authenticated account's
shared iMessage line. Pending contacts become verified after the recipient
sends an inbound iMessage or SMS to the returned line phone number.

### Body Parameters

- `phone_number: string`

  Contact phone number. E.164 is recommended; US local numbers are accepted.

### Returns

- `data: optional object { contact, line, verification_instructions }`

  - `contact: object { created_at, phone_number, updated_at, 2 more }`

    - `created_at: string`

    - `phone_number: string`

      Contact phone number in E.164 format

    - `updated_at: string`

    - `verification_status: "pending" or "verified"`

      - `"pending"`

      - `"verified"`

    - `verified: boolean`

      Whether this contact has completed verification by messaging the shared line

  - `line: object { phone_number, type }`

    - `phone_number: string`

      Shared Sendblue line the contact must message to complete verification

    - `type: "shared"`

      - `"shared"`

  - `verification_instructions: string`

    Null when the contact is already verified

### Example

```http
curl https://api.sendblue.co/v3/verified-contacts \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "phone_number": "+12125550199"
        }'
```

#### Response

```json
{
  "data": {
    "contact": {
      "created_at": "2026-08-12T18:32:12.000Z",
      "phone_number": "+12125550199",
      "updated_at": "2026-08-12T18:32:12.000Z",
      "verification_status": "pending",
      "verified": false
    },
    "line": {
      "phone_number": "+12125550101",
      "type": "shared"
    },
    "verification_instructions": "Ask +12125550199 to send any iMessage or SMS to +12125550101 to complete verification."
  }
}
```

## Get a verified contact

**get** `/v3/verified-contacts/{phone_number}`

Retrieve one verified-contact route by phone number for the authenticated account.

### Path Parameters

- `phone_number: string`

### Returns

- `data: optional object { contact, line }`

  - `contact: object { created_at, phone_number, updated_at, 2 more }`

    - `created_at: string`

    - `phone_number: string`

      Contact phone number in E.164 format

    - `updated_at: string`

    - `verification_status: "pending" or "verified"`

      - `"pending"`

      - `"verified"`

    - `verified: boolean`

      Whether this contact has completed verification by messaging the shared line

  - `line: object { phone_number, type }`

    - `phone_number: string`

      Shared Sendblue line the contact must message to complete verification

    - `type: "shared"`

      - `"shared"`

### Example

```http
curl https://api.sendblue.co/v3/verified-contacts/$PHONE_NUMBER \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

#### Response

```json
{
  "data": {
    "contact": {
      "created_at": "2026-08-12T18:32:12.000Z",
      "phone_number": "+12125550199",
      "updated_at": "2026-08-12T18:32:12.000Z",
      "verification_status": "pending",
      "verified": false
    },
    "line": {
      "phone_number": "+12125550101",
      "type": "shared"
    }
  }
}
```

## Domain Types

### Verified Contact List Response

- `VerifiedContactListResponse object { data }`

  - `data: optional object { contacts, line }`

    - `contacts: array of object { created_at, phone_number, updated_at, 2 more }`

      - `created_at: string`

      - `phone_number: string`

        Contact phone number in E.164 format

      - `updated_at: string`

      - `verification_status: "pending" or "verified"`

        - `"pending"`

        - `"verified"`

      - `verified: boolean`

        Whether this contact has completed verification by messaging the shared line

    - `line: object { phone_number, type }`

      - `phone_number: string`

        Shared Sendblue line the contact must message to complete verification

      - `type: "shared"`

        - `"shared"`

### Verified Contact Create Response

- `VerifiedContactCreateResponse object { data }`

  - `data: optional object { contact, line, verification_instructions }`

    - `contact: object { created_at, phone_number, updated_at, 2 more }`

      - `created_at: string`

      - `phone_number: string`

        Contact phone number in E.164 format

      - `updated_at: string`

      - `verification_status: "pending" or "verified"`

        - `"pending"`

        - `"verified"`

      - `verified: boolean`

        Whether this contact has completed verification by messaging the shared line

    - `line: object { phone_number, type }`

      - `phone_number: string`

        Shared Sendblue line the contact must message to complete verification

      - `type: "shared"`

        - `"shared"`

    - `verification_instructions: string`

      Null when the contact is already verified

### Verified Contact Retrieve Response

- `VerifiedContactRetrieveResponse object { data }`

  - `data: optional object { contact, line }`

    - `contact: object { created_at, phone_number, updated_at, 2 more }`

      - `created_at: string`

      - `phone_number: string`

        Contact phone number in E.164 format

      - `updated_at: string`

      - `verification_status: "pending" or "verified"`

        - `"pending"`

        - `"verified"`

      - `verified: boolean`

        Whether this contact has completed verification by messaging the shared line

    - `line: object { phone_number, type }`

      - `phone_number: string`

        Shared Sendblue line the contact must message to complete verification

      - `type: "shared"`

        - `"shared"`