ASDinCloudDocs

The list object

View as Markdown

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.
GET/api/v1/lists

Lists 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.

Retrieve a list

View as Markdown
GET/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.

Create a list

View as Markdown
POST/api/v1/lists

Creates 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.

Update a list

View as Markdown
PATCH / PUT / POST/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.

Delete a list

View as Markdown
DELETE/api/v1/lists/{id}
POST/api/v1/lists/{id}/delete

Removes 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.

The list contact object

View as Markdown

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.

List contacts

View as Markdown
GET/api/v1/lists/{list_id}/contacts

Lists 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.

Retrieve a contact

View as Markdown
GET/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.

Create a contact

View as Markdown
POST/api/v1/lists/{list_id}/contacts

Adds 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.

Update a contact

View as Markdown
PATCH / PUT/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.

Delete a contact

View as Markdown
DELETE/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.

Import contacts

View as Markdown
POST/api/v1/lists/{list_id}/contacts/import

Imports 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.