Upload Opportunity Batch

This endpoint accepts a CSV file containing multiple opportunity records and processes them asynchronously. The request returns immediately with a jobId that can be used to track progress and retrieve results.

The CSV is validated server-side before the job is created. If validation fails, a 400 response is returned with detailed row-level errors — no job is created and nothing is stored.

Headers:

AuthorizationstringRequired

The authorization token for accessing the API. The header value should be set to "Bearer {your-access-token}", where {your-access-token} is the access token assigned to the user.

Content-TypestringRequired

Must be multipart/form-data. The CSV file should be submitted as a form file part.

CSV Structure:

The CSV file must include a header row. The following columns are supported:

OpportunityDateTimestringRequired

The date the opportunity was captured. Must be in one of the following ISO 8601 formats (UTC):

  • yyyy-MM-dd
  • yyyy-MM-ddTHH:mm:ss
  • yyyy-MM-ddTHH:mm:ss.ffffff

Must not be a future date.

CurrencyCodestringRequired

ISO 4217 currency code for the opportunity value. E.g. GBP, USD, EUR.

OpportunityValuedecimalRequired

The monetary value of the opportunity. Must be a valid number.

PipelineStagestringRequired

The pipeline stage for the opportunity. E.g. Proposal, Negotiation.

Visitor Identifiers (at least one required)

At least one of the following must be provided per row.

RaIdstring

The Ruler Analytics visitor ID.

EmailAddressstring

The visitor's email address.

PhoneNumberstring

The visitor's phone number.

PayloadValuestring

A custom payload identifier value.

Labelstring

An opportunity label. This column may appear multiple times in the header to attach several labels to a single row (e.g. two Label columns for Deal and Inbound).

Referencestring

A unique reference identifier for the opportunity record.

AdditionalDataPropertiesstring

Custom key-value properties. Each entry uses the format Name=X,Value=Y. Separate multiple entries with a semicolon:

"Name=Source,Value=Google;Name=Campaign,Value=Spring"

Validation Rules:

  • All required columns must be present in the CSV header.
  • Unknown column names are rejected.
  • Duplicate column names are rejected (except Label).
  • OpportunityValue must be a valid number and must not be empty.
  • OpportunityDateTime must match an accepted ISO 8601 format and must not be a future date.
  • Each row must contain at least one visitor identifier.
  • Rows with the same visitor identifier and OpportunityDateTime combination are flagged as duplicates.
  • AdditionalDataProperties must follow the Name=X,Value=Y format if provided.
Request
POST
{siteId}/opportunity/upload/batch
curl -X POST \
  'https://rest.rulerapi.com/v1/{siteId}/opportunity/upload/batch' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/opportunities.csv'
Response
202 Accepted
{
    "jobId": "{{jobId}}"
}
Processing

The job is processed asynchronously. Use the returned jobId to poll GET /{siteId}/batch/{jobId}/status until the status is complete, partialcomplete, or failed.