Contacts API
The Contacts API lets you manage your contact database programmatically. Create individual contacts, bulk import up to 100 at a time, upsert by email address, and query with flexible filtering and pagination.
Endpoints
GET
/api/v1/contactsList contactsPOST
/api/v1/contactsCreate a contactGET
/api/v1/contacts/{id}Get contact by IDPUT
/api/v1/contacts/{id}Update a contactDELETE
/api/v1/contacts/{id}Delete a contactPUT
/api/v1/contacts/upsertCreate or update by emailPOST
/api/v1/contacts/bulkBulk create (max 100)List endpoints support ?limit, ?offset, ?updatedSince, and ?fields query parameters. See the API Overview for details.
Create Contact Request
Request body for POST /api/v1/contacts and PUT /api/v1/contacts/upsert.
CreateContactRequest
| Property | Type | Required | Description |
|---|---|---|---|
firstName | string | ✓ | Contact's first name |
lastName | string | ✓ | Contact's last name |
email | string | ✓ | Email address (used as unique identifier for upsert) |
phone | string? | — | Phone number |
mobile | string? | — | Mobile number |
title | string? | — | Job title |
department | string? | — | Department |
linkedInUrl | string? | — | LinkedIn profile URL |
twitterHandle | string? | — | Twitter handle |
address | string? | — | Street address |
city | string? | — | City |
state | string? | — | State/Province |
country | string? | — | Country |
postalCode | string? | — | Postal/ZIP code |
companyId | Guid? | — | Associated company ID |
lifecycleStage | string | — | Lead lifecycle stage (default: "lead") |
leadSource | string? | — | How the lead was acquired |
leadScore | int? | — | Lead score (0-100) |
tags | string? | — | Comma-separated tags |
notes | string? | — | Free-text notes |
ownerId | Guid? | — | Assigned owner user ID |
Contact Response
Returned by all GET, POST, and PUT endpoints.
ContactResponse
| Property | Type | Required | Description |
|---|---|---|---|
id | Guid | ✓ | Unique identifier |
tenantId | Guid | ✓ | Tenant identifier |
firstName | string | ✓ | First name |
lastName | string | ✓ | Last name |
fullName | string | ✓ | Computed full name |
email | string | ✓ | Email address |
phone | string? | — | Phone |
mobile | string? | — | Mobile |
title | string? | — | Job title |
department | string? | — | Department |
companyId | Guid? | — | Associated company |
lifecycleStage | string | ✓ | Current stage |
leadSource | string? | — | Lead source |
leadScore | int? | — | Lead score |
tags | string? | — | Tags |
isUnsubscribed | bool | ✓ | Email opt-out status |
lastContactedAt | DateTime? | — | Last contact date |
ownerId | Guid? | — | Owner |
createdAt | DateTime | ✓ | Creation timestamp |
updatedAt | DateTime | ✓ | Last update timestamp |
Code Examples
List Contacts
curl "https://your-tenant.rallycrm.io/api/v1/contacts?limit=50&offset=0" \
-H "X-Api-Key: rk_live_your_api_key_here"Create a Contact
curl -X POST "https://your-tenant.rallycrm.io/api/v1/contacts" \
-H "X-Api-Key: rk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Sarah",
"lastName": "Chen",
"email": "sarah.chen@example.com",
"phone": "+1-555-0142",
"title": "VP of Engineering",
"companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"lifecycleStage": "lead",
"leadSource": "website"
}'Upsert by Email
Creates a new contact or updates an existing one matched by email address. The response includes an action field indicating whether the record was created or updated.
curl -X PUT "https://your-tenant.rallycrm.io/api/v1/contacts/upsert" \
-H "X-Api-Key: rk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Sarah",
"lastName": "Chen",
"email": "sarah.chen@example.com",
"title": "CTO",
"lifecycleStage": "opportunity"
}'Example Responses
List Contacts
[
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"firstName": "Sarah",
"lastName": "Chen",
"fullName": "Sarah Chen",
"email": "sarah.chen@example.com",
"phone": "+1-555-0142",
"mobile": null,
"title": "VP of Engineering",
"department": "Engineering",
"companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"lifecycleStage": "opportunity",
"leadSource": "website",
"leadScore": 82,
"tags": "enterprise,tech",
"isUnsubscribed": false,
"lastContactedAt": "2025-06-10T14:30:00Z",
"ownerId": "e4d909c2-90d0-4b2b-88c5-8e9a0fa1e4b1",
"createdAt": "2025-01-15T09:00:00Z",
"updatedAt": "2025-06-10T14:30:00Z"
}
]Upsert Response
{
"action": "created",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}Bulk Create Response
{
"created": 3,
"updated": 0,
"failed": 0,
"createdIds": [
"d290f1ee-6c54-4b01-90e6-d701748f0851",
"f47ac10b-58cc-4372-a567-0e02b2c3d479",
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"errors": []
}