curl --request POST \
--url https://api.upliftai.org/v1/contact-sources \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Edversity admissions leads",
"kind": "google_sheets",
"ref": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms!Admissions",
"mapping": {
"nameColumn": "طالب علم کا نام",
"phoneColumn": "موبائل",
"attributeColumns": [
"پروگرام",
"شہر"
]
}
}
'{
"sourceId": "c616feca-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"organizationId": "a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"projectId": "c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Edversity admissions leads",
"kind": "google_sheets",
"ref": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms!Admissions",
"mapping": {
"nameColumn": "طالب علم کا نام",
"phoneColumn": "موبائل",
"attributeColumns": [
"پروگرام",
"شہر"
]
},
"createdAt": "2026-08-18T05:19:03.311Z",
"updatedAt": "2026-08-18T05:19:03.311Z",
"version": 1
}{
"message": [
"name must be shorter than or equal to 120 characters",
"name should not be empty",
"name must be a string",
"Only 'google_sheets' connected sources can be registered; use the preview endpoint for csv/paste uploads",
"ref should not be empty",
"ref must be a string"
],
"error": "Bad Request",
"statusCode": 400
}{
"message": "invalid authorization",
"error": "Unauthorized",
"statusCode": 401
}{
"message": "Forbidden resource",
"error": "Forbidden",
"statusCode": 403
}Register a Google Sheet as a source
Register a Google Sheet as a reusable contact source. The source is a pointer to the live sheet, not a copy: a campaign reads whatever rows the sheet holds at that moment, so to change the contacts you edit the sheet. The registration itself never changes — to point at a different sheet or use a different column mapping, register a new source.
Nothing is checked at registration today (this may change): a wrong spreadsheet id, an unshared sheet, or an unknown connectionId all register fine and only fail later — so preview the source right after creating it.
Only a Google Sheet can be registered here. For a CSV or pasted rows, create a contact list instead — a one-time import rather than a live source. Column naming rules: Special column names.
curl --request POST \
--url https://api.upliftai.org/v1/contact-sources \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Edversity admissions leads",
"kind": "google_sheets",
"ref": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms!Admissions",
"mapping": {
"nameColumn": "طالب علم کا نام",
"phoneColumn": "موبائل",
"attributeColumns": [
"پروگرام",
"شہر"
]
}
}
'{
"sourceId": "c616feca-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"organizationId": "a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"projectId": "c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Edversity admissions leads",
"kind": "google_sheets",
"ref": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms!Admissions",
"mapping": {
"nameColumn": "طالب علم کا نام",
"phoneColumn": "موبائل",
"attributeColumns": [
"پروگرام",
"شہر"
]
},
"createdAt": "2026-08-18T05:19:03.311Z",
"updatedAt": "2026-08-18T05:19:03.311Z",
"version": 1
}{
"message": [
"name must be shorter than or equal to 120 characters",
"name should not be empty",
"name must be a string",
"Only 'google_sheets' connected sources can be registered; use the preview endpoint for csv/paste uploads",
"ref should not be empty",
"ref must be a string"
],
"error": "Bad Request",
"statusCode": 400
}{
"message": "invalid authorization",
"error": "Unauthorized",
"statusCode": 401
}{
"message": "Forbidden resource",
"error": "Forbidden",
"statusCode": 403
}Authorizations
Project API key (sk_api_…).
Body
- Public link-shared sheet
- Private sheet via Google connection
Label for the source.
1 - 120google_sheets Spreadsheet id from the sheet URL, optionally ! plus an A1 range or tab name ({id}!Leads, {id}!A:C). A bare id reads columns A–ZZ of the first tab. The sheet must be shared as anyone-with-the-link; it is read with the platform's own credential.
1Column overrides. Whatever you leave out is auto-detected from the headers.
Show child attributes
Show child attributes
Response
The registered source.
google_sheets Sources cannot be edited, so this stays 1.
Column overrides. Whatever you leave out is auto-detected from the headers.
Show child attributes
Show child attributes