Create, update, find and delete contacts, and manage suppression status. 6 operation(s) in the Loops REST API v1 (OpenAPI 1.21.6).
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/loops:loops-contacts-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Loops OpenAPI Spec Contacts API
description: This is the OpenAPI Spec for the Loops API.
version: 1.21.6
servers:
- url: https://app.loops.so/api
tags:
- name: Contacts
description: Manage contacts in your audience
paths:
/v1/contacts/create:
post:
operationId: createContact
tags:
- Contacts
summary: Create a contact
description: Add a contact to your audience.
x-mint:
href: /api-reference/create-contact
content: <Tip>If you want to "update or create" contacts, consider using the [Update a contact](https://loops.so/docs/api-reference/update-contact) endpoint instead.</Tip>
requestBody:
description: You can add custom contact properties as keys in this request (of type `string`, `number`, `boolean` or `date`. [See available date formats](https://loops.so/docs/contacts/properties#dates)). Make sure to create the properties in Loops before using them in API calls.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactRequest'
required: true
responses:
'200':
description: Successful create.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSuccessResponse'
'400':
description: Bad request (e.g. invalid email address).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
'409':
description: Email or `userId` already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
security:
- apiKey: []
/v1/contacts/update:
put:
operationId: updateContact
tags:
- Contacts
summary: Update a contact
description: 'Update a contact by `email` or `userId`. You must provide one of these parameters.
If you want to update a contact''s email address, the contact will first need a `userId` value. You can then make a request containing the `userId` field along with an updated email address.
This endpoint will create a contact if a matching contact does not already exist in your audience.
Provide either `email` or `userId` to identify the contact you want to update. If both are provided, the system will look for a contact with either a matching `email` or `userId` value. If a contact is found for one of the values (e.g. `email`), the other value (e.g. `userId`) will be updated. If a contact is not found, a new contact will be created using both `email` and `userId` values.'
x-mint:
href: /api-reference/update-contact
content: 'Update a contact by `email` or `userId`. You must provide one of these parameters.
If you want to update a contact''s email address, the contact will first need a `userId` value. You can then make a request containing the `userId` field along with an updated email address.
This endpoint will create a contact if a matching contact does not already exist in your audience.
<Note>Provide either `email` or `userId` to identify the contact you want to update. If both are provided, the system will look for a contact with either a matching `email` or `userId` value. If a contact is found for one of the values (e.g. `email`), the other value (e.g. `userId`) will be updated. If a contact is not found, a new contact will be created using both `email` and `userId` values.</Note>'
metadata:
sidebarTitle: Update a contact
description: Update or create a contact.
requestBody:
description: You can add custom contact properties as keys in this request (of type `string`, `number`, `boolean` or `date`. [See available date formats](https://loops.so/docs/contacts/properties#dates)). Make sure to create the properties in Loops before using them in API calls.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactUpdateRequest'
required: true
responses:
'200':
description: Successful update.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSuccessResponse'
'400':
description: Bad request (e.g. `email` or `userId` are missing).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
security:
- apiKey: []
/v1/contacts/find:
get:
operationId: findContact
tags:
- Contacts
summary: Find a contact
description: Search for a contact by `email` or `userId`. Only one parameter is allowed.
x-mint:
href: /api-reference/find-contact
content: Search for a contact by `email` or `userId`. Only one parameter is allowed.
metadata:
description: Find a contact by email address or user ID.
parameters:
- name: email
in: query
required: false
description: Email address (URI-encoded)
schema:
type: string
- name: userId
in: query
required: false
schema:
type: string
responses:
'200':
description: List of contacts (or an empty array if no contact was found). Contact objects will include any custom properties.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Contact'
'400':
description: Bad request (e.g. invalid email address).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
security:
- apiKey: []
/v1/contacts/delete:
post:
operationId: deleteContact
tags:
- Contacts
summary: Delete a contact
description: Delete a contact by `email` or `userId`.
x-mint:
href: /api-reference/delete-contact
content: Delete a contact by `email` or `userId`.
metadata:
sidebarTitle: Delete a contact
description: Delete a contact by email address or user ID.
requestBody:
description: Include only one of `email` or `userId`.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactDeleteRequest'
required: true
responses:
'200':
description: Successful delete.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactDeleteResponse'
'400':
description: Bad request (e.g. `email` and `userId` are both provided).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'404':
description: Contact not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
security:
- apiKey: []
/v1/contacts/suppression:
get:
operationId: getContactSuppression
tags:
- Contacts
summary: Get suppression status for a contact
description: Retrieve suppression status and removal quota for a contact by `email` or `userId`. Include only one query parameter.
x-mint:
href: /api-reference/check-contact-suppression
metadata:
title: Check contact suppression status
sidebarTitle: Check suppression
description: Check if a contact is suppressed by email address or user ID.
parameters:
- name: email
in: query
required: false
description: Email address (URI-encoded)
schema:
type: string
- name: userId
in: query
required: false
schema:
type: string
responses:
'200':
description: Successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSuppressionStatusResponse'
'400':
description: Bad request (e.g. invalid email address).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'404':
description: Contact not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
security:
- apiKey: []
delete:
operationId: removeContactSuppression
tags:
- Contacts
summary: Remove a contact from suppression list
description: Remove a suppressed contact from the suppression list by `email` or `userId`. Include only one query parameter.
x-mint:
href: /api-reference/remove-contact-suppression
metadata:
title: Remove contact from suppression
sidebarTitle: Remove suppression
description: Remove suppression for a contact by email address or user ID.
parameters:
- name: email
in: query
required: false
description: Email address (URI-encoded)
schema:
type: string
- name: userId
in: query
required: false
schema:
type: string
responses:
'200':
description: Successful removal.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSuppressionRemoveResponse'
'400':
description: Bad request (e.g. contact is not suppressed).
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'404':
description: Contact not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactFailureResponse'
'405':
description: Wrong HTTP request method.
security:
- apiKey: []
components:
schemas:
MailingListSubscriptions:
type: object
description: 'Manage mailing list subscriptions.
Include key-value pairs of mailing list IDs and a `boolean` denoting if the contact should be added (`true`) or removed (`false`) from the list.'
examples:
- cm06f5v0e45nf0ml5754o9cix: true
cm16k73gq014h0mmj5b6jdi9r: false
ContactSuccessResponse:
type: object
properties:
success:
type: boolean
examples:
- true
id:
type: string
examples:
- clh3k9m2p4q6r8s0t2v4x6z8
required:
- success
- id
examples:
- success: true
id: clh3k9m2p4q6r8s0t2v4x6z8
ContactFailureResponse:
type: object
properties:
success:
type: boolean
examples:
- false
message:
type: string
examples:
- Invalid email address.
required:
- success
- message
examples:
- success: false
message: Invalid email address.
ContactSuppressionRemovalQuota:
type: object
properties:
limit:
type: number
description: The number of suppression removals allowed in a rolling 30 day period.
examples:
- 100
remaining:
type: number
description: The remaining number of suppression removals left in the current 30 day period.
examples:
- 10
required:
- limit
- remaining
ContactSuppressionStatusResponse:
type: object
properties:
contact:
type: object
properties:
id:
type: string
description: The contact's Loops ID.
email:
type: string
description: The contact's email address.
userId:
type:
- string
- 'null'
description: The contact's unique user ID.
required:
- id
- email
- userId
isSuppressed:
type: boolean
description: Whether the contact is suppressed.
removalQuota:
$ref: '#/components/schemas/ContactSuppressionRemovalQuota'
description: The removal quota for the contact.
required:
- contact
- isSuppressed
- removalQuota
examples:
- contact:
id: clh3k9m2p4q6r8s0t2v4x6z8
email: alex@company.com
userId: usr_7f8e9d0c1b2a
isSuppressed: false
removalQuota:
limit: 5
remaining: 5
ContactFields:
type: object
properties:
email:
type: string
examples:
- alex@company.com
description: The contact's email address.
firstName:
type: string
description: The contact's first name.
examples:
- Alex
lastName:
type: string
description: The contact's last name.
examples:
- Rivera
source:
type: string
description: A custom source value to replace the default “API”.
examples:
- API
subscribed:
type: boolean
description: Whether the contact will receive campaign and workflow emails. All new contacts are subscribed by default.
userGroup:
type: string
description: The contact's user group.
examples:
- customers
userId:
type: string
description: A unique user ID (for example, from an external application).
examples:
- usr_7f8e9d0c1b2a
mailingLists:
$ref: '#/components/schemas/MailingListSubscriptions'
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
examples:
- email: alex@company.com
firstName: Alex
lastName: Rivera
subscribed: true
userGroup: customers
userId: usr_7f8e9d0c1b2a
mailingLists:
clm2k8j4h6g0f8d6s4a2b0z8: true
favoriteColor: blue
ContactDeleteResponse:
type: object
properties:
success:
type: boolean
examples:
- true
message:
type: string
examples:
- Contact deleted.
required:
- success
- message
ContactRequest:
allOf:
- $ref: '#/components/schemas/ContactFields'
- type: object
required:
- email
Contact:
type: object
properties:
id:
type: string
description: The contact's Loops ID.
examples:
- clh3k9m2p4q6r8s0t2v4x6z8
email:
type: string
description: The contact's email address.
examples:
- alex@company.com
firstName:
type:
- string
- 'null'
description: The contact's first name.
examples:
- Alex
lastName:
type:
- string
- 'null'
description: The contact's last name.
examples:
- Rivera
source:
type: string
description: The source the contact was created from.
examples:
- API
subscribed:
type: boolean
description: Whether the contact will receive campaign and workflow emails.
examples:
- true
userGroup:
type: string
description: The contact's user group.
examples:
- customers
userId:
type:
- string
- 'null'
description: The contact's unique user ID.
examples:
- usr_7f8e9d0c1b2a
mailingLists:
type: object
description: Mailing lists the contact is subscribed to, represented by key-value pairs of mailing list IDs and `true`.
examples:
- cm06f5v0e45nf0ml5754o9cix: true
optInStatus:
type:
- string
- 'null'
description: Double opt-in status. This will be `null` for contacts unless they are created via a form while double opt-in is enabled.
enum:
- accepted
- pending
- rejected
- null
examples:
- accepted
examples:
- id: clh3k9m2p4q6r8s0t2v4x6z8
email: alex@company.com
firstName: Alex
lastName: Rivera
source: API
subscribed: true
userGroup: customers
userId: usr_7f8e9d0c1b2a
mailingLists:
clm2k8j4h6g0f8d6s4a2b0z8: true
optInStatus: accepted
ContactDeleteRequest:
type: object
properties:
email:
type: string
examples:
- alex@company.com
userId:
type: string
examples:
- usr_7f8e9d0c1b2a
required:
- email
- userId
examples:
- email: alex@company.com
userId: usr_7f8e9d0c1b2a
ContactSuppressionRemoveResponse:
type: object
properties:
success:
type: boolean
description: Whether the suppression removal was successful.
examples:
- true
message:
type: string
examples:
- Email removed from suppression list.
removalQuota:
$ref: '#/components/schemas/ContactSuppressionRemovalQuota'
required:
- success
- message
- removalQuota
ContactUpdateRequest:
allOf:
- $ref: '#/components/schemas/ContactFields'
- type: object
properties:
email:
type: string
description: The contact's email address. **Required if `userId` is not provided.**
subscribed:
type: boolean
description: Whether the contact will receive campaign and workflow emails. We recommend leaving this field out of your update requests unless you specifically want to unsubscribe (`false`) or re-subscribe (`true`) a contact. All new contacts are subscribed by default.
userId:
type: string
description: The contact's unique user ID. **Required if `email` is not provided.**
anyOf:
- required:
- email
- required:
- userId
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
examples:
- email: alex@company.com
firstName: Alex
lastName: Rivera
subscribed: true
userGroup: customers
userId: usr_7f8e9d0c1b2a
mailingLists:
clm2k8j4h6g0f8d6s4a2b0z8: true
favoriteColor: blue
securitySchemes:
apiKey:
type: http
scheme: bearer