Loops provides a REST API to manage your contacts and send events. You can use this API to add contacts to your Loops audience, update their attributes, and send events to Loops.
Start here if you want to use the Loops API to add contacts to your Loops audience, update their attributes, and send events to Loops.
To get started, you’ll need an API key. Visit the Loops settings page and click “Generate new key”
This creates an API key. You can assign it a human-readable name:
We suggest using a different API key for different purposes. You can revoke an API key at any time with the trash icon.
When making an API call, add an Authorization header and set the API key as a Bearer token:
You can test your API key by making a GET request to https://app.loops.so/api/v1/api-key. If successful, you will receive { "success": true }
As a Curl request (replace d2d561f5ff80136f69b4b5a31b9fb3c9 with your own API key):
To ensure the quality of service for all users, our API is rate limited. This means there’s a limit to the number of requests your application can make to our API in a certain time frame. The baseline rate limit is 10 requests per second per team.
To see your current usage, we provide the following response headers in every API response:
x-ratelimit-limit: The maximum number of requests you can make per second.
x-ratelimit-remaining: The number of requests remaining in the current rate limit window.
Here is an example of a successful response with rate limit headers:
If you exceed this limit, you’ll receive a response with HTTP status 429 Too Many Requests. Here is an example of a failed response with rate limit headers:
It’s important to handle these 429 responses in your application. We recommend implementing retries with an exponential backoff strategy.
If your use case requires a higher limit, please contact us and we’ll be happy to discuss your needs.
Sometimes things go wrong. Here are some tips to help you debug your API requests.
If you are having trouble with the API, we recommend using a tool like Postman to test your requests.
Handling CORS Errors:
The Loops API does not support cross-origin requests made from client-side JavaScript. To avoid CORS errors, make sure to issue your requests from a server-side application.
Dealing with “Not Authenticated” Codes:
Make sure you have generated an API key from the Loops settings page and that you are including it in your requests.
Your API key should be included in the “Authorization” header of your request, following the format “Authorization: Bearer “.
Handling Rate Limiting (429 Response):
The Loops API allows a maximum of 10 requests per second per team. If you receive a “429 Too Many Requests” response, this means you have exceeded this limit.
The “x-ratelimit-limit” and “x-ratelimit-remaining” headers in the response can provide information about your current rate limit usage.
Authorization Header:
Ensure that you are correctly including the “Authorization” header in your requests. The value of this header should follow the format “Bearer “.
Handling 400-level Responses:
400-level responses typically indicate that there was a problem with the request. The response body will contain more information about what went wrong, so be sure to check it for details.
Check on your request type (GET, POST, PUT, DELETE) and ensure that you are using the correct one for the endpoint you are trying to access.
Handling Issues with Contacts API:
Make sure to include at least the “email” field in your requests when adding or updating contacts.
For searching contacts, replace URI_ENCODED_EMAIL with the URL-encoded email you are looking for in the GET request.
Handling Issues with Events API:
When sending events, ensure that both the “email” and “eventName” fields are included in your requests.
If you have followed these steps and are still experiencing issues, don’t hesitate to reach out to the Loops team for further assistance.
You can add contacts to your Loops audience by making a POST to the https://app.loops.so/api/v1/contacts/create endpoint. You can submit the following object for the body:
{"email":"[email protected]","firstName":"Adam","lastName":"Kaczmarek","favoriteColor":"blue","userGroup":"Founders","source":"Signup form Service"}
You can update contacts to your Loops audience by making a PUT to the https://app.loops.so/api/v1/contacts/update endpoint. You can submit the following object for the body:
{"email":"[email protected]","firstName":"Adam","lastName":"Kaczmarek","favoriteColor":"blue","userGroup":"Founders","source":"Signup form Service"}
The only required field is “email”. If there is no contact with this email, one will be created. You can add additional fields as you need for the contact (favoriteColor is not a standard field).
You can search your existing contacts by email using a GET request to the https://app.loops.so/api/v1/contacts/find?email=URI_ENCODED_EMAIL endpoint.
Be sure to replace URI_ENCODED_EMAIL with the email you are looking for. For example, searching your list for [email protected] would use https://app.loops.so/api/v1/contacts/find?email=adam%40loops.so
Note that this endpoint will always return an array. If no contact is found, you will receive an empty array. If the contact is found, you will receive an array with a single contact object.
You can send an event to Loops audience by making a POST to the https://app.loops.so/api/v1/events/send endpoint. You can submit the following object for the body:
Both fields are required. If no contact with that email address exists, one will be added to your list. You can add additional fields as you need to update the contact attributes, similar to the contact update API.
You may also include contact properties in the event payload. These properties will be updated on the contact record when the event is received.
