Skip to main content
Version: v1.0

Sync Protocol

Contract for the two REST endpoints your CRM must expose to integrate with Spot2.

Properties endpoint​

Main endpoint that returns your active properties.

GET https://your-crm.com/api/v1/spot2/properties

Parameters​

ParameterTypeRequiredDescription
updated_sinceISO 8601Yes (except first cycle)Returns only properties modified since this date. Spot2 omits it on the first cycle, and your API must return the full catalog. Your API may use an equivalent name — Spot2 adapts.
limitintegerNoPage size. Default: 200.
Pagination—Yesoffset-based (see below).

Behavior​

  • Spot2 sends updated_since with the date of the last successful cycle. Your API filters and returns only items with updated_at > updated_since.
  • If your API cannot filter by date, it cannot integrate with this contract.
  • On the first cycle (no previous timestamp), Spot2 does not send updated_since. Your API must return the full catalog of active properties.

Authentication​

Choose one of these methods. We configure the credentials on our side.

MethodImplementation
API Key (header)Header x-api-key: <your-key>. Simple, recommended.
API Key (query param)Query parameter ?api_key=<your-key>.
Bearer TokenHeader Authorization: Bearer <your-token>.
Custom headerAny other header you define.

Credential requirements:

  • Must not auto-expire. If you need to rotate it, notify us in advance.
  • Must have read-only scope over properties.
  • We recommend a dedicated key exclusively for Spot2 integration.

Pagination​

Your API must support offset-based pagination.

GET /properties?offset=0&limit=200

The response must include:

  • meta.next: full URL for the next page, or null if it's the last.
  • meta.total_count: total number of properties in the feed.

We stop when meta.next is null. Recommended page size: 100–200.

Response format​

The response is a JSON object with two sections:

  1. Property list in an array under the data field.
  2. Pagination metadata in a separate meta object.

Each property must follow the schema defined in Property Schema.

HTTP codes​

StatusMeaning
200Success. Feed received correctly.
204Empty feed (no properties modified since updated_since). Not an error.
400Missing updated_since (except first cycle).
400Malformed updated_since (must be ISO 8601).
503Maintenance. Include Retry-After.

Rate limits​

Our default limit is 60 requests per minute. We respect Retry-After.

Timeout​

Default timeout: 30 seconds per request.

Sync frequency​

  • Scheduled cycles: typically every 1 hour (configurable between 5 minutes and 24 hours).
  • On-demand cycles: we can run a manual cycle if you need to force a sync.

Deletion endpoint​

Endpoint to report delistings. Mandatory.

GET https://your-crm.com/api/v1/spot2/properties/deleted

Parameters​

ParameterTypeRequiredDescription
sinceISO 8601Yes (except first cycle)Returns IDs deleted since this date. Spot2 omits it on the first cycle, and your API must return all deleted IDs it knows about.

Response format​

{
  "deleted_ids": ["prop-001", "prop-002", "prop-005"],
  "since": "2026-06-29T14:30:00Z",
  "generated_at": "2026-06-30T10:00:00Z"
}
FieldTypeDescription
deleted_idsstring[]external_id of properties deleted since since.
sinceISO 8601Echo of the received parameter.
generated_atISO 8601Timestamp when this response was generated.

Behavior​

  • Spot2 sends since with the date of the last successful cycle.
  • Your API returns all external_ids deleted after that date.
  • If since is older than your retention, return all available IDs.
  • Minimum deletion history retention: 30 days.
  • If you return an empty array ("deleted_ids": []), there are no delistings this cycle.

Authentication and rate limits​

Same as the main endpoint. Timeout: 30 seconds.

What NOT to do​

  • Don't change item order between paginated requests.
  • Don't use infinite pagination without an end indicator.
  • Don't compress the response with non-standard algorithms.

Next steps​