Lists
View as MarkdownContact lists group people in a sport. The list and its contacts have separate endpoints.
On this page
- The list object
- List listsGET
/api/v1/lists - Retrieve a listGET
/api/v1/lists/{id} - Create a listPOST
/api/v1/lists - Update a listPATCH / PUT / POST
/api/v1/lists/{id} - Delete a listDELETE
/api/v1/lists/{id}POST/api/v1/lists/{id}/delete - The list contact object
- List contactsGET
/api/v1/lists/{list_id}/contacts - Retrieve a contactGET
/api/v1/lists/{list_id}/contacts/{contact_id} - Create a contactPOST
/api/v1/lists/{list_id}/contacts - Update a contactPATCH / PUT
/api/v1/lists/{list_id}/contacts/{contact_id} - Delete a contactDELETE
/api/v1/lists/{list_id}/contacts/{contact_id} - Import contactsPOST
/api/v1/lists/{list_id}/contacts/import
Contact lists group people in a sport. The list and its contacts have separate endpoints.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger- Sport associated with the record.
namestring- Display name, up to 191 characters.
descriptionstring or null- Optional description. Omit it or send null to clear it on update.
tscinteger- Creation time as Unix seconds.
tsuinteger- Last update time as Unix seconds.
contacts_countinteger- Number of contacts. Included when listing or retrieving lists.
/api/v1/listsLists list records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Query parameters
qstring- Search list names and descriptions.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, name, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns records in data, the counts before and after text search, and the echoed draw marker.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/lists/{id}Returns one list by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the list.
Returns
The list is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/listsCreates a list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Body parameters
namestringRequired- Display name, up to 191 characters.
descriptionstring or null- Optional description. Omit it or send null to clear it on update.
Returns
The created list is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Send the body as a JSON object.
422- One or more fields failed validation.
/api/v1/lists/{id}Updates a list by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the list.
Body parameters
namestringRequired- Display name, up to 191 characters.
descriptionstring or null- Optional description. Omit it or send null to clear it on update.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- Send the body as a JSON object.
422- One or more fields failed validation.
/api/v1/lists/{id}/api/v1/lists/{id}/deleteRemoves a contact list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the list.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The list could not be removed.
A list contact holds contact details and communication preferences for a single list.
Attributes
idinteger- Identifier assigned by the API.
list_idinteger- ID of the parent list.
firstnamestring or null- Given name, up to 100 characters. Alias name.
surnamestring or null- Family name, up to 100 characters.
companystring or null- Company or club name, up to 191 characters.
emailstring or null- Email address, up to 191 characters. Stored in lowercase.
phonestring or null- Phone number, up to 32 characters.
communication_consentinteger- 1 if the contact opted in, otherwise 0.
is_activeinteger- 1 for active, 0 for inactive.
imported_atinteger or null- Time of CSV import as Unix seconds, if applicable.
tscinteger- Creation time as Unix seconds.
tsuinteger- Last update time as Unix seconds.
/api/v1/lists/{list_id}/contactsLists contacts in one list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
Query parameters
is_activeinteger- Use 1 for active contacts or 0 for inactive contacts.
qstring- Search name, company, email, or phone.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, firstname, surname, company, email, phone, communication_consent, is_active, imported_at, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns records in data, the counts before and after text search, and the echoed draw marker.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/lists/{list_id}/contacts/{contact_id}Returns one contact from the list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
contact_idintegerRequired- ID of a contact in this list.
Returns
Returns the contact in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/lists/{list_id}/contactsAdds a contact to the list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
Body parameters
firstnamestring or null- Given name, up to 100 characters. Alias name.
surnamestring or null- Family name, up to 100 characters.
companystring or null- Company or club name, up to 191 characters.
emailstring or null- Email address, up to 191 characters. Stored in lowercase.
phonestring or null- Phone number, up to 32 characters.
communication_consentboolean- Whether the contact opted in. Defaults to false. Alias consent.
is_activeboolean- Whether the contact is active. Defaults to true. Alias active.
Returns
Returns the created contact in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Send the body as a JSON object.
404- The requested record was not found.
422- One or more fields failed validation.
/api/v1/lists/{list_id}/contacts/{contact_id}Replaces the details of a contact in the list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
contact_idintegerRequired- ID of a contact in this list.
Body parameters
firstnamestring or null- Given name, up to 100 characters. Alias name.
surnamestring or null- Family name, up to 100 characters.
companystring or null- Company or club name, up to 191 characters.
emailstring or null- Email address, up to 191 characters. Stored in lowercase.
phonestring or null- Phone number, up to 32 characters.
communication_consentboolean- Whether the contact opted in. Defaults to false. Alias consent.
is_activeboolean- Whether the contact is active. Defaults to true. Alias active.
Send all the values you want to keep. The request clears omitted contact details and applies the defaults for activation and consent.
Returns
Returns the update confirmation.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Send the body as a JSON object.
404- The requested record was not found.
422- One or more fields failed validation.
/api/v1/lists/{list_id}/contacts/{contact_id}Removes a contact from the list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
contact_idintegerRequired- ID of a contact in this list.
Returns
Returns confirmation that the contact was removed.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The contact could not be removed.
404- The requested record was not found.
/api/v1/lists/{list_id}/contacts/importImports contacts from a CSV file. A row with a matching email updates that contact in this list.
Permissions
Send your API key in X-API-Key. Required permissions are Lists → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
list_idintegerRequired- ID of the contact list.
Body parameters
fileCSV fileRequired- Upload as multipart/form-data. Include a header row. Use commas, semicolons, or tabs.
Accepted columns include firstname, surname, company, email, phone, communication_consent, and is_active.
Returns
Returns counts and any row errors in data. Each row error has a line number and reason.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Supply a valid upload with a .csv filename.
404- The requested record was not found.