API Introduction
The Loops REST API lets you manage your contacts, send events and send transactional email.
Authentication
Your Loops API key should never be used client side or exposed to your end users.
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.
Authentication Steps
Authentication Steps
To get started, you’ll need an API key. Go to Settings -> API in Loops and click Generate 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
If successful, you will receive the following response:
Here’s an example Curl request (replace d2d561f5ff80136f69b4b5a31b9fb3c9 with your own API key):
Rate Limiting
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.
Rate Limiting Details
Rate Limiting Details
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.
Debugging
Sometimes things go wrong. Here are some tips to help you debug your API requests.
Debugging Steps
Debugging Steps
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 401 Unauthorized “Invalid API key” errors
Make sure you have generated an API key from Settings -> API 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 YOUR_API_KEY.
Handling rate limiting (429 Responses)
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.
Handling other 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.
”Some body key or value is longer than allowable”
If you receive this error, it means that a value in the request body is too long. We support a maximum of 500 characters for each value, including the opening and closing quotes. Please reduce the length of the values in your request and try again.
If you have followed these steps and are still experiencing issues, don’t hesitate to reach out to the Loops team for further assistance.
OpenAPI spec
Get started quickly with the Loops API using our OpenAPI documents.
You can import these documents into an API client like Postman or Insomnia to see and use all of our endpoints, with example requests and expected responses.
- YAML: app.loops.so/openapi.yaml
- JSON: app.loops.so/openapi.json
SDKs
SDKs are software packages built on top of the API, making it easier to integrate into your project.
JavaScript
The official JavaScript/TypeScript SDK for Loops.
Nuxt
The official Nuxt module for Loops.
PHP
The official PHP SDK for Loops.
Ruby
The official Ruby SDK for Loops.
Unofficial SDKs
The following SDKs are community-submitted and have not been officially reviewed or endorsed by Loops. We recommend thoroughly testing and reviewing the code before integrating it into your project.
- Laravel by PlutoLinks
- PHP by PlutoLinks
- Ruby on Rails by Daniel Friis
API Reference
The base URL for the API is https://app.loops.so/api
Contacts
Manage contacts.
Contact properties
Manage contact properties.
Mailing lists
View your mailing lists.
Events
Send events to trigger emails in loops.
Transactional email
Send a transactional email.
Custom fields
View your account’s custom contact properties.
This endpoint is now deprecated in favor of List contact properties.
API key
Test your API key.