Lookup request

Please check the best practice section to understand which API request will be better for your use case.

Send single request

POST https://a.looplookup.com/api/v1/lookup/

This endpoint allows you to submit your message to the sending queue. When a message in the queue will be ready to send in iMessage, an attempt will be made to deliver it to the recipient.

Headers

Name	Type	Description
Authorization*	String	API Key
Content-Type*	String	application/json

Request Body

Name	Type	Description
contact*	String	Phone number or Email.
region	String	Value in ISO-2 country code. For example: US, GB, CA AU, etc. This parameter should be passed only if you passed a phone number to contact without a country code.
contact_details	Bool	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.

200: OK Request accepted

{
    "request_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
    "success": true,
    "contact": "[phone]",
}

A phone number will be converted to the next format [phone], without spaces and brackets. An email will be converted into a lowercase format.

400: Bad Request Request failed

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

402: Payment Required No available request. Need purchase additional requests.

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

Important

When you receive success response with code 200 from send request, it means that the server accepted your request for lookup and added it to the queue.

To handle lookup results for your requests, need to observe Callbacks or use API method to check the status by request ID which you received in JSON response.

We recommend using callbacks to track statuses, as you will receive a response as soon as the results are ready.

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.

Valid phone number format examples:

• 13231234567

• [phone]

• [phone]

• [phone]

• 1 (323)-123-4567

Send bulk lookup

If you need to send a large volume of contacts, please don't send more than 2-3 thousand contacts in each bulk request. Our server will keep connection only for 30 seconds, if we're unable to process your volume during this time your request may be rejected.

POST https://a.looplookup.com/api/v1/lookup/

Headers

Name	Type	Description
Authorization*	String	API Key
Content-Type*	String	application/json

Request Body

Name	Type	Description
contacts*	Array	An array of contacts. Should contains phone numbers in international formats or emails. Example: ["[phone]", "[email protected]", “1(787)111-22-33”]. Invalid recipients will be skipped.
contact_details	bool	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.
region	String	Value in ISO-2 country code. For example: US, GB, CA AU, etc. This parameter should be passed only if you passed phone numbers without a country code.

200: OK Request accepted

{
  "success": true,
  "requests": [
    {
      "contact": "[phone]",
      "request_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C"
    }
  ]
}

A phone number will be converted to the next format [phone], without spaces and brackets. An email will be converted into a lowercase format.

400: Bad Request Request failed

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

402: Payment Required No available request. Need purchase additional requests.

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

Cancel bulk request

Request to cancel bulk lookup

DELETE https://a.looplookup.com/api/v1/bulk-lookup/delete/{id}/

Path Parameters

Name	Type	Description
id*	String	Bulk request ID

Headers

Name	Type	Description
Authorization*	String	API Key
Content-Type*	String	application/json

200: OK Request accepted

{
  "success": true,
  "requests": [
    {
      "contact": "[phone]",
      "request_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C"
    }
  ]
}

A phone number will be converted to the next format [phone], without spaces and brackets. An email will be converted into a lowercase format.

400: Bad Request Request failed

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

Failed requests

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

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.

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

Error codes

Code	Description
100	Bad request
110	Missing credentials in request
120	One or more required parameters for the request are missing
125	Authorization key is invalid or does not exist
130	Secret key is invalid or does not exist
150	No "recipient" parameter in request
160	Invalid recipient
170	Invalid recipient email
180	Invalid recipient phone number
190	A phone number is not mobile
400	No available requests/credits on your balance
500	Your account is suspended
510	Your account is blocked
530	Your account is suspended due to debt

Best Practices

Performance

Since the lookup process is asynchronous, each request will be collected in the lookup queue. Due to the lookup queue having a limited resource for lookups per second*, the queue will determine the priority for each request based on the type of your request and the volume of requests you have sent.

A single request is good if you need to lookup one contact at a random time. Because it's has a high priority to start lookup immediately. But it is slow if you need to process large volumes in a short time. The queue for a single lookup goes according to the FIFO rules. This means that every time you send a request, you add a new operation to the queue. The duration for each operation could take a few seconds. So, if you send 100 single lookup requests simultaneously, the last operation can be finished after a delay of 100-400 seconds.

If you need to lookup a large list of contacts, it's highly recommended to use the bulk API request only.

In this case, the lookup queue can calculate the resources that will be needed for your volume and process them as soon as possible. If you have a list of about ~10 thousand contacts, try to send them as bulk requests in batches of 2-3 thousand contacts in each request. Don't send such large volumes as single requests, it will always take longer since they will always be scheduled according to the FIFO rules.