Best Practices

Partial Updates (PATCH vs PUT)

The PulsePoint API uses PATCH for partial updates on campaign, line item, and tactic endpoints. This means:

1. Only include fields you want to update
2. Omitted fields will retain their current values
3. Fields will not be nulled by omission

Use PUT (Replace Line Item) when you want to fully replace a resource's configuration. Any fields omitted from a PUT request will be reset to their defaults.

Resource Creation Order

The PulsePoint Platform has a defined hierarchy. Resources must be created in the following order — each level depends on the one above it existing first:

1. Account — your top-level entity (provisioned by PulsePoint)
2. Advertiser — retrieved via Get Advertiser IDs by Account ID. New advertisers are provisioned by PulsePoint
3. Campaign — the parent container for all line items
4. Line Item — defines budget, flights, inventory type, and targeting settings
5. Tactic — the most granular level; controls creative assignment, bidding, and targeting
6. Creative Assignment — assign creatives to a tactic before it can serve

Attempting to create a resource before its parent exists will result in a 404 or validation error.

Pagination

Several endpoints return paginated results using cursor-based pagination. To retrieve all results:

1. Make your initial request — the response will include a pagination object
2. Check pagination.has_more — if true, more results are available
3. Pass the pagination.next_cursor value as the cursor query parameter in your next request
4. Repeat until has_more is false

{
  "data": { "data": [...] },
  "pagination": {
    "limit": 50,
    "total": 312,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzNDU2fQ",
    "next_cursor_url": "/RestApi/v2/meta/behavioralSegments?cursor=eyJpZCI6MTIzNDU2fQ&limit=50"
  }
}

The default page size is 50 and the maximum is 100. Use the limit query parameter to control page size.

Date and Time Formatting

Different endpoints use different date formats. Always check the field-level notes for the endpoint you are using:

All times are interpreted in the timezone specified on the line item. If no timezone is specified, Eastern Time is used as the default.

Using Numeric IDs

All resources in the PulsePoint API are referenced by numeric IDs, not by name. Before creating line items or tactics, use the Account Assets endpoints to retrieve the IDs you need:

• Advertiser IDs → Get Advertiser IDs by Account ID
• Campaign IDs → Get Campaign IDs by Account and Advertiser ID
• Creative IDs → Get Creatives By Account
• Targeting segment IDs → Get Behavioral Targeting Segments

Start with Read-Only Requests

The PulsePoint Platform API operates in a production environment only. We recommend familiarizing yourself with the API using GET requests before creating or modifying resources. This lets you verify your authentication, understand the data structure, and confirm you are working with the correct account and advertiser IDs before making any changes.

Error Handling

• Check the HTTP status code first to determine the error category before parsing the response body
• Use error.code for programmatic logic — this field is stable and consistent. Do not write logic that parses error.message strings
• Check the details array — validation errors often return multiple field-level issues at once; handle all of them
• Include requestId when contacting support — every API response includes a requestId (success) or request_id (error) field that PulsePoint support can use to look up the exact request
• Implement retry logic for 429 errors — use the retryAfter value in the response to determine when to retry
• Use exponential backoff for 500 errors — do not retry immediately; wait and retry with increasing delays

See Standard Responses and Errors for the full list of error codes and response formats.