Deals API

The Deals API lets you manage your sales pipeline programmatically. Create deals, move them through stages, track values and probabilities, upsert by name and pipeline, and use BANT qualification scoring to prioritize your opportunities.

Endpoints

GET
/api/v1/dealsList deals
POST
/api/v1/dealsCreate a deal
GET
/api/v1/deals/{id}Get deal by ID
PUT
/api/v1/deals/{id}Update a deal
DELETE
/api/v1/deals/{id}Delete a deal
PATCH
/api/v1/deals/{id}/stageMove deal to stage
PUT
/api/v1/deals/upsertCreate or update by name + pipeline
POST
/api/v1/deals/bulkBulk create
GET
/api/v1/deals/{id}/bantGet BANT qualification
PUT
/api/v1/deals/{id}/bantUpdate BANT qualification

List endpoints support ?limit, ?offset, ?updatedSince, and ?fields query parameters. See the API Overview for details.

Create Deal Request

Request body for POST /api/v1/deals and PUT /api/v1/deals/upsert.

CreateDealRequest

PropertyTypeRequiredDescription
pipelineIdGuid✓Pipeline ID
stageIdGuid✓Stage ID
namestring✓Deal name
contactIdGuid?—Associated contact
companyIdGuid?—Associated company
valuedecimal?—Deal value
currencystring?—Currency code (default: "USD")
probabilityint?—Win probability %
expectedCloseDateDateTime?—Expected close date
notesstring?—Notes
ownerIdGuid?—Owner

Deal Response

Returned by all GET, POST, and PUT endpoints.

DealResponse

PropertyTypeRequiredDescription
idGuid✓Unique identifier
tenantIdGuid✓Tenant identifier
pipelineIdGuid✓Pipeline ID
stageIdGuid✓Current stage ID
stageNamestring✓Current stage name
contactIdGuid?—Associated contact ID
contactNamestring?—Associated contact name
companyIdGuid?—Associated company ID
companyNamestring?—Associated company name
namestring✓Deal name
valuedecimal?—Deal value
currencystring?—Currency code
probabilityint?—Win probability %
expectedCloseDateDateTime?—Expected close date
actualCloseDateDateTime?—Actual close date
statusstring✓Deal status (default: "open")
notesstring?—Notes
ownerIdGuid?—Owner ID
ownerNamestring?—Owner name
lastActivityAtDateTime?—Last activity date
bantScoreint?—BANT qualification score (0-100)
isBantQualifiedbool✓Whether deal passes BANT threshold
createdAtDateTime✓Creation timestamp
updatedAtDateTime✓Last update timestamp

Move Deal to Stage

Use the PATCH /api/v1/deals/{id}/stage endpoint to advance or move a deal to a different pipeline stage without updating other fields.

MoveDealStageRequest

PropertyTypeRequiredDescription
stageIdGuid✓Target stage ID

BANT Qualification

BANT (Budget, Authority, Need, Timeline) qualification helps you prioritize deals based on structured criteria. Use the BANT endpoints to read and update qualification data for any deal.

BantQualification

PropertyTypeRequiredDescription
budgetint?—Budget score (0-25)
authorityint?—Authority score (0-25)
needint?—Need score (0-25)
timelineint?—Timeline score (0-25)
budgetNotesstring?—Budget qualification notes
authorityNotesstring?—Authority qualification notes
needNotesstring?—Need qualification notes
timelineNotesstring?—Timeline qualification notes
totalScoreint✓Computed total score (0-100)
isQualifiedbool✓Whether total meets qualification threshold

Code Examples

Create a Deal

curl -X POST "https://your-tenant.rallycrm.io/api/v1/deals" \
  -H "X-Api-Key: rk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "stageId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "name": "Acme Corp - Enterprise License",
    "contactId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "companyId": "b5c7e1a2-3d4f-5678-9abc-def012345678",
    "value": 75000,
    "currency": "USD",
    "probability": 60,
    "expectedCloseDate": "2025-09-30T00:00:00Z"
  }'

Move Deal to Stage

curl -X PATCH "https://your-tenant.rallycrm.io/api/v1/deals/c8f9a0b1-2d3e-4f56-7890-abcdef123456/stage" \
  -H "X-Api-Key: rk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "9e8d7c6b-5a4f-3210-fedc-ba9876543210"
  }'

Update BANT Qualification

curl -X PUT "https://your-tenant.rallycrm.io/api/v1/deals/c8f9a0b1-2d3e-4f56-7890-abcdef123456/bant" \
  -H "X-Api-Key: rk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 20,
    "authority": 25,
    "need": 22,
    "timeline": 18,
    "budgetNotes": "Approved Q3 budget of $80k",
    "authorityNotes": "Decision maker confirmed (VP Eng)"
  }'

Example Responses

Get Deal

{
  "id": "c8f9a0b1-2d3e-4f56-7890-abcdef123456",
  "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pipelineId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "stageId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "stageName": "Proposal",
  "contactId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "contactName": "Sarah Chen",
  "companyId": "b5c7e1a2-3d4f-5678-9abc-def012345678",
  "companyName": "Acme Corporation",
  "name": "Acme Corp - Enterprise License",
  "value": 75000,
  "currency": "USD",
  "probability": 60,
  "expectedCloseDate": "2025-09-30T00:00:00Z",
  "actualCloseDate": null,
  "status": "open",
  "notes": "Proposal sent, awaiting feedback",
  "ownerId": "e4d909c2-90d0-4b2b-88c5-8e9a0fa1e4b1",
  "ownerName": "James Miller",
  "lastActivityAt": "2025-06-14T11:00:00Z",
  "bantScore": 85,
  "isBantQualified": true,
  "createdAt": "2025-04-01T09:00:00Z",
  "updatedAt": "2025-06-14T11:00:00Z"
}

BANT Qualification

{
  "budget": 20,
  "authority": 25,
  "need": 22,
  "timeline": 18,
  "budgetNotes": "Approved Q3 budget of $80k",
  "authorityNotes": "Decision maker confirmed (VP Eng)",
  "needNotes": null,
  "timelineNotes": null,
  "totalScore": 85,
  "isQualified": true
}

Upsert Response

{
  "action": "created",
  "id": "c8f9a0b1-2d3e-4f56-7890-abcdef123456"
}

Bulk Create Response

{
  "created": 5,
  "updated": 0,
  "failed": 0,
  "createdIds": [
    "c8f9a0b1-2d3e-4f56-7890-abcdef123456",
    "d9e0f1a2-3b4c-5d6e-7f80-91a2b3c4d5e6",
    "e0f1a2b3-4c5d-6e7f-8091-a2b3c4d5e6f7",
    "f1a2b3c4-5d6e-7f80-9102-b3c4d5e6f7a8",
    "a2b3c4d5-6e7f-8091-0213-c4d5e6f7a8b9"
  ],
  "errors": []
}

Next Steps

Contacts API →

Manage contacts, upsert by email, and bulk import.

Companies API →

Manage company records with CRUD and upsert by domain.

Activities API →

Log calls, meetings, notes, and tasks via the API.

API Overview →

Authentication, rate limits, pagination, and error handling.

Rally Support

We typically reply in a few hours

Hi! 👋 How can we help you today?