> For the complete documentation index, see [llms.txt](https://docs.looplookup.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.looplookup.com/lookup-api/send-message.md).

# Lookup request

Check whether the contact is using iMessage, FaceTime, or WhatsApp.

&#x20;<mark style="color:green;">`POST`</mark> `https://a.looplookup.com/api/v1/lookup/`

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | String | API Key          |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json |

#### Request Body

<table><thead><tr><th width="150.359375">Name</th><th width="97.140625">Type</th><th>Description</th></tr></thead><tbody><tr><td>contact<mark style="color:red;">*</mark></td><td>String</td><td>Phone number or Email.</td></tr><tr><td>services<mark style="color:red;">*</mark></td><td>Array</td><td>Services that need to be looked up. Possible values: <code>imessage</code>, <code>facetime</code>, <code>whatsapp</code>. You should pass it as an array of strings: <code>"services": ["imessage", "whatsapp"]</code>. WhatsApp doesn't work with email addresses.</td></tr><tr><td>region</td><td>String</td><td><p>Value in <a href="https://en.wikipedia.org/wiki/ISO_3166-2">ISO-2 country code</a>. For example: <code>US</code>, <code>GB</code>, <code>CA</code> <code>AU</code>, etc.</p><p>This parameter should be passed only if you passed a phone number to <code>contact</code> without a country code.</p></td></tr><tr><td>contact_details</td><td>Bool</td><td>Callback/Webhook will contain additional information related to the phone number. For example: carrier name, number type (landline or mobile), country, timezone and etc. Requests with this parameter may take a little bit more time.</td></tr></tbody></table>

**JSON payload example**

```json
{
  "contact": "+13231112233",
  "services": ["imessage", "whatsapp", "facetime"]
}
```

or

```json
{
  "contact": "steve@apple.com",
  "services": ["imessage", "facetime"]
}
```

**JSON response example**

{% tabs %}
{% tab title="200: OK Request accepted" %}
Check the [result example](#results-example) section for more details.

```json
{
  "contact": "+13231112233",
  "request_id": "2f31A2B6-Fd5F-4118-A85f-DafbBcB7f4C2",
  "result_v1": {
    ...
  }
}
```

A phone number will be converted to the next format `+13231112233`, without spaces and brackets. An email address will be converted to lowercase.
{% endtab %}

{% tab title="400: Bad Request Request failed" %}

```json
{
    "success": false,
    "code": 100,
    "message": "Failed description",
}
```

{% endtab %}

{% tab title="402: Payment Required No available request. Need purchase additional requests." %}

```json
{
    "success": false,
    "code": 400,
    "message": "Failed description",
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Supported phone number formats**

Recipient phone numbers should be only in international formats with a country code. Otherwise will be impossible to verify a phone number.

Plus prefix `+` is optional. Spaces, dashes '`-`', brackets '`(123)`' - also optional.&#x20;

Valid phone number format examples:

* 13231234567
* +13231111111&#x20;
* +1 (323) 1111111
* +1 323 123 4567
* 1 (323)-123-4567

{% endhint %}

### Failed requests

If your request has a failed status, you will receive a JSON response with the following format:

{% hint style="info" %}
The "message" field is optional and is intended to briefly inform the developer about the cause of the error. Please do not pass this to the destination users who initiated the message request. Use the "code" field to map errors and show localized error text to them.
{% endhint %}

```json
{
    "success": false,
    "code": 100,
    "message": "string"
}
```

Then you can match the [error code](/lookup-api/error-codes.md) to determine what may be wrong.

### Limits

By default, all users have a limit of 20 lookup requests per minute. The limit starts counting when you send the first lookup request and resets after 60 seconds.

To increase your limit, please contact support and describe your use case.&#x20;

### Results example

```json
{
  "contact": "+13231112233",
  "request_id": "2f31A2B6-Fd5F-4118-A85f-DafbBcB7f4C2",
  "result_v1": {
    "apple_services": {
      "facetime": {
        "status": "available",
        "date": "2022-12-13",
        "links": {
          "facetime_audio": "facetime-audio://+13231112233",
          "facetime": "facetime://+13231112233",
          "tel": "tel://+13231112233"
        }
      },
      "imessage": {
        "status": "available",
        "date": "2022-12-13",
        "links": {
          "imessage": "imessage://+13231112233",
          "sms": "sms://+13231112233"
        }
      }
    },
    "whatsapp": {
      "status": "available",
      "date": "2022-12-13",
      "links": {
          "whatsapp": "whatsapp://send?phone=+13231112233",
        }
    },
    "carrier": {
      "carrier": "Verizon",
      "number_type": "mobile"
    },
    "country": {
      "flag": "🇺🇸",
      "iso2": "US",
      "iso3": "USA",
      "name": "United States of America",
      "description": "CA",
      "numeric": 840
    },
    "currencies": [
      "USD", "EUR", "GBP"
    ],
    "format": {
      "e164": "+13231112233",
      "international": "+1 323-111-2233",
      "national": "(323) 111-2233",
      "out_of_usa": "1 (323) 111-2233",
      "rfc3966": "tel:+1-323-111-2233"
    },
    "time_zones": [
      "America/Los_Angeles"
    ]
  }
}
```

{% hint style="info" %}
Some of the fields, such as `carrier`, `timezone`, or `currencies`, are NOT data that was returned by the contact carrier. You should treat these values as approximations based on the phone number area code or country code. Also, in some countries (for example, in the USA), it's not possible to detect a carrier based on the patterns described above.
{% endhint %}

#### Possible JSON fields in the response

<table><thead><tr><th width="150">Field</th><th width="150">Type</th><th width="450.1684011352885">Description</th></tr></thead><tbody><tr><td>request_id</td><td>String</td><td>Unique identifier of your request.</td></tr><tr><td>webhook_id</td><td>String</td><td>Unique identifier of the event.</td></tr><tr><td>contact</td><td>String</td><td>Phone number will be converted to the next format: <code>+13231112233</code>, without spaces and brackets. Email addresses will be converted to lowercase.</td></tr><tr><td>result_v1</td><td>Object</td><td>Object with lookup <a href="#result-object">result</a>.</td></tr></tbody></table>

#### Result object

**facetime**

<table><thead><tr><th width="100.33333333333331">Field</th><th width="83">Type</th><th></th></tr></thead><tbody><tr><td>status</td><td>String</td><td>Possible values: <code>available</code>, <code>unavailable</code>.</td></tr><tr><td>date</td><td>String</td><td>Last known date of this data. This can show you how up-to-date this data is. Format of the date: <code>2023-12-31</code> The value may be <code>null</code> if the <code>status</code> is not available.</td></tr><tr><td>links</td><td>Object</td><td><p><code>{</code> </p><p><code>"facetime_audio": "facetime-audio://+13231112233",</code></p><p><code>"facetime": "facetime://+13231112233",</code> </p><p><code>"tel": "tel://+13231112233"</code></p><p><code>}</code><br>Deep links that can be used to open a chat with this contact immediately.</p></td></tr></tbody></table>

**imessage**

<table><thead><tr><th width="101.33333333333331">Field</th><th width="87">Type</th><th></th></tr></thead><tbody><tr><td>status</td><td>String</td><td>Possible values: <code>available</code>, <code>unavailable</code>.</td></tr><tr><td>date</td><td>String</td><td>Last known date of this data. This can show you how up-to-date this data is. Format of the date: <code>2023-12-31</code> The value may be <code>null</code> if the <code>status</code> is not available.</td></tr><tr><td>links</td><td>Object</td><td><p><code>{</code> </p><p><code>"imessage": "imessage://+13231112233",</code> </p><p><code>"sms": "sms://+13231112233"</code> </p><p><code>}</code><br>Deep links that can be used to open a chat with this contact immediately.</p></td></tr></tbody></table>

**whatsapp**

<table><thead><tr><th width="101.33333333333331">Field</th><th width="87">Type</th><th></th></tr></thead><tbody><tr><td>status</td><td>String</td><td>Possible values: <code>available</code>, <code>unavailable</code>.</td></tr><tr><td>date</td><td>String</td><td>Last known date of this data. This can show you how up-to-date this data is. Format of the date: <code>2023-12-31</code> The value may be <code>null</code> if the <code>status</code> is not available.</td></tr><tr><td>links</td><td>Object</td><td><p><code>{</code> </p><p><code>"whatsapp": "whatsapp://send?phone=+13231112233"</code> </p><p><code>}</code><br>Deep links that can be used to open a chat with this contact immediately.</p></td></tr></tbody></table>