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 contacts
POST
/api/v1/contactsCreate a contact
GET
/api/v1/contacts/{id}Get contact by ID
PUT
/api/v1/contacts/{id}Update a contact
DELETE
/api/v1/contacts/{id}Delete a contact
PUT
/api/v1/contacts/upsertCreate or update by email
POST
/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

PropertyTypeRequiredDescription
firstNamestringContact's first name
lastNamestringContact's last name
emailstringEmail address (used as unique identifier for upsert)
phonestring?Phone number
mobilestring?Mobile number
titlestring?Job title
departmentstring?Department
linkedInUrlstring?LinkedIn profile URL
twitterHandlestring?Twitter handle
addressstring?Street address
citystring?City
statestring?State/Province
countrystring?Country
postalCodestring?Postal/ZIP code
companyIdGuid?Associated company ID
lifecycleStagestringLead lifecycle stage (default: "lead")
leadSourcestring?How the lead was acquired
leadScoreint?Lead score (0-100)
tagsstring?Comma-separated tags
notesstring?Free-text notes
ownerIdGuid?Assigned owner user ID

Contact Response

Returned by all GET, POST, and PUT endpoints.

ContactResponse

PropertyTypeRequiredDescription
idGuidUnique identifier
tenantIdGuidTenant identifier
firstNamestringFirst name
lastNamestringLast name
fullNamestringComputed full name
emailstringEmail address
phonestring?Phone
mobilestring?Mobile
titlestring?Job title
departmentstring?Department
companyIdGuid?Associated company
lifecycleStagestringCurrent stage
leadSourcestring?Lead source
leadScoreint?Lead score
tagsstring?Tags
isUnsubscribedboolEmail opt-out status
lastContactedAtDateTime?Last contact date
ownerIdGuid?Owner
createdAtDateTimeCreation timestamp
updatedAtDateTimeLast 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": []
}

Next Steps

Rally Support

We typically reply in a few hours

Hi! 👋 How can we help you today?