Objects API

Authenticate to the Objects API by sending your project's Write Key along with a request. Authentication uses HTTP Basic Auth, which involves a 'username:password' that is base64 encoded and pre-pended with the string 'Basic'.

In practice that means taking a Segment source Write Key, 'abc123', as the username, adding a colon, and then the password field is left empty. After base64 encoding 'abc123:' becomes 'YWJjMTIzOg=='; and this is passed in the authorization header like so: 'Authorization: Basic YWJjMTIzOg=='.

Set up an HTTP API source type in Segment. You will use this source write key for authenticating with the Objects API.

In order to send data to Segment's HTTP API, the content-type header must be set to 'application/json'.

The Objects API returns a 200 response in most cases, similar to the Tracking API. It will return a 400 if a request payload is malformed.

It's highly recommended that you batch your objects where you can. This will allow you to make significantly fewer requests to Segment. To batch your requests, simply pass in more than one object into the objects array.

The Objects API is asynchronous by default. This means that if object updates are processed close together, they can be processed out of order. To change this default behavior, you can set the header Synchronous: true to ensure synchronous delivery of objects downstream.

For Business plans with access to Regional Segment, you can use the host configuration parameter to interact with the desired region:

1. Oregon (Default) — objects.segment.com
2. Dublin — objects.euw1.segment.com

Segment recommends that you use snake case when naming any object properties.

1
{
2
  "properties": {
3
    "name": "Charming Beach Room Facing Ocean",
4
    "location": "Lihue, HI",
5
    "review_count": 47
6
  }
7
}

You should use plural collection names wherever possible. The collection name should describe the group of one or many objects within the collection.

1
"collection": "rooms"
2
"collection": "products"
3
"collection": "reviews"

Segment de-dupes objects with the same ID and merges properties. By sending in partial objects with the same object ID, Segment merges the properties and you can query the latest data in your data warehouse.

For example, if you make the following requests with the following payloads:

1
{
2
  "collection": "rooms",
3
  "objects": [
4
    {
5
      "id": "2561341",
6
      "properties": {
7
        "name": "Charming Beach Room Facing Ocean",
8
        "location": "Lihue, HI",
9
        "review_count": 47
10
      }
11
    }
12
  ]
13
}
14

15
{
16
  "collection": "rooms",
17
  "objects": [
18
    {
19
      "id": "2561341",
20
      "properties": {
21
        "name": "Charming Beach Room Facing Ocean",
22
        "location": "Lihue, HI",
23
        "review_count": 48
24
      }
25
    }
26
  ]
27
}

When you query your warehouse you will see the following:

select id, name, location, review_count from airbnb.rooms

 '261341' | 'Charming Beach Room Facing Ocean' | 'Lihue, HI' | 48

set lets you send in a collection and array of objects (to a maximum of 10 objects), each with a unique object ID.

Example set call:

POST https://objects.segment.com/v1/set

1
{
2
  "collection": "rooms",
3
  "objects": [
4
    {
5
      "id": "2561341",
6
      "properties": {
7
        "name": "Charming Beach Room Facing Ocean",
8
        "location": "Lihue, HI",
9
        "review_count": 47
10
      }
11
    }, {
12
      "id": "2561342",
13
      "properties": {
14
        "name": "College town feel — plenty of bars nearby",
15
        "location": "Austin, TX",
16
        "review_count": 32
17
      }
18
    }
19
  ]
20
}

This call sends a collection of "rooms". "rooms" becomes the table name in your data warehouse, and each individual object in the array becomes a row in that table.

Each object inside of the objects array must consist of the following parameters:

You can use the objects-go library to send object data easily from your Go server to the Objects API.

You can use the objects-go library like this:

1
Client.Set(&objects.Object{
2
  ID: "room1000",
3
  Collection: "rooms"
4
  Properties: map[string]interface{}{
5
    "name": "Charming Beach Room Facing Ocean",
6
    "location": "Lihue, HI",
7
    "review_count": 47,
8
}})
9

10
// Second call on the same object
11
Client.Set(*objects.Object{
12
  ID: "room1000",
13
  Collection: "rooms"
14
  Properties: map[string]interface{}{
15
    "owner": "Calvin",
16
    "public_listing": true,
17
}})
18

19
// Make sure objects are flushed before your main goroutine exits
20
Client.Close()

View the Objects-go library on GitHub in the @segmentio/objects-go repository.

Here is a curl example of how to get started:

1
curl https://objects.segment.com/v1/set \
2
   -u PROJECT_WRITE_KEY: \
3
   -H 'Content-Type: application/json' \
4
   -X POST -d '{"collection":"rooms","objects":[{"id": "2561341","properties": {"name": "Charming Beach Room Facing Ocean","location":"Lihue, HI","review_count":47}}]}'

No; you should continue use analytics.identify to identify your customers. Segment syncs that to your data warehouse as select * from project.users.

Segment's Reverse ETL product supports this use case.

On Change - You can .set when the data changes, for example, when a user updates an account field on your website.

Scheduled job - You can run scheduled scripts hourly or nightly that pull data from your database and send it to Segment. This is a totally fine approach, even if you load the same data in every night.