Direct Destinations

With a Direct destination, Segment will forward all of the incoming data for our mutual customers to your service’s HTTPS endpoint in realtime.

A Direct d gives you complete control over how you want to store, transform and process the data. It means that our customers can immediately start sending you data from any one of our sources—from the browser, from their mobile apps, or from their servers—with no added work. Segment Business plan customers can also replay histroic data, which means you can demonstrate the value of your tool rapidly.

This type of destination works well for analytics tools, email marketing tools, attribution tools, CRMs, raw data tools, helpdesks, customer success tools, etc.

Becoming a Direct Partner is a quick five-step process. By starting or continuing this process, you agree to the Segment Platform Partners Agreement.

Five-step Process:

  1. Complete the destination survey
  2. Build an endpoint to recieve customer data
  3. Test your destination
  4. Submit your technical survey for review
  5. Private Beta

1. Complete the destination survey

Complete an destination survey so we know you’re building an destination and can support you.

Please do not move forward in the process until you hear back from our Partners team.

2. Build an endpoint to receive customer data

The following sections outline what kind of requests and data we send to you, and what we expect in return.

Accepting Segment Data

In order to receive data from Segment, you’ll need a server ready to accept HTTPS requests. You’ll give us a static endpoint to send data to, and that endpoint must:

  • Accept POST requests. We’ll send customer data to the endpoint you designate in POST requests.
  • Accept JSON data. This is the format we’ll send data to you in.
  • Use HTTPS. We transmit potentially sensitive data on behalf of customers, and using HTTPS goes a long way toward making sure their data stays safe.

Authorization

We’ll send your user’s API key with requests, which you can then use to authenticate requests. Note that this is the API key you give to your users; it’s not a Segment API key.

We’ll send the key in the Authorization header using the Basic authentication type. It’ll be Base64 encoded, with your user’s API key as the username and an empty password. For example, if your user’s API key was segment, we’d Base64 encode the string 'segment:' and prepend the string 'Basic '. (Note that the colon is always present, even when the password is absent.) This would result in a final string of 'Basic c2VnbWVudDo='. This is what is contained in the Authorization header.

You’ll need to decode the string when you receive it, just like any Authorization header.

See the headers section for more details.

Headers

We’ll send you the following HTTP headers with all our requests:

HeaderDescriptionExample
AcceptWe accept any content type, but ignore responses unless this header is set to application/json.Accept: */*
AuthorizationWe’ll send you your user’s API token in this header, with the Basic authentication type.Authorization: Basic c2VnbWVudDo=
Cache-ControlEach request we send you is a new event, and so we expect you to not implement caching on your end.Cache-Control: no-cache
ConnectionWe use HTTP/1.1’s keep-alive functionality whenever possible (but you don’t have to).Connection: Keep-Alive
Content-LengthWe’ll always send you the length of the request in bytes.Content-Length: 348
Content-TypeWe indicate the type of data we’re sending you (we’ll always send you JSON), along with our vendor type.Content-Type: application/json
User-AgentWe’ll send you this field every time. You can count on us!User-Agent: Segment

Request Body

Our spec standardizes the data that you can expect from Segment. You can choose to implement four types types of calls:

  • Who is this? .identify(userId, traits)
  • What are they doing? .track(userId, event, properties)
  • Where are they doing it? .page(userId, pageName, properties)
  • What group are they part of? .group(userId, groupId, groupTraits)

For example, you may want to implement the .identify(userId, traits) call to create contacts in an email marketing application. You can expect the following customer infomation as a JSON object in the call body

{
  "anonymous_id": "507f191e810c19729de860ea",
  "context": {
    "ip": "8.8.8.8",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
  },
  "message_id": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "received_at": "2015-02-23T22:28:55.387Z",
  "sent_at": "2015-02-23T22:28:55.111Z",
  "traits": {
    "name": "Peter Gibbons",
    "email": "peter@initech.com",
    "plan": "premium",
    "logins": 5
  },
  "type": "identify",
  "user_id": "97980cfea0067",
  "version": "1.1"
}

To learn more about the 4 API calls we support, and the semantic fields and event names we recognize, please follow the Segment spec for all contributions.

Formatting

Segment allows users to send their data formatted using the conventions of their host language; in a user’s Ruby code, they can use snake_case, while in their JavaScript code they can use camelCase.

To make integrating with Segment easy, we send you all keys in snake_case.For example, when a user sends us this JSON:

{
  "address": {
    "city": "Newport Coast",
    "postalCode": "92606",
    "state": "CA",
    "street": "1 Lucille Lane"
  },
  "CreatedAt": "1967-12-14T08:00:00.000Z",
  "NAME": "Michael Bluth",
  "user_id": 12345
}

We will send you:

{
  "address": {
    "city": "Newport Coast",
    "postal_code": "92606",
    "state": "CA",
    "street": "1 Lucille Lane"
  },
  "created_at": "1967-12-14T08:00:00.000Z",
  "name": "Michael Bluth",
  "user_id": 12345
}

Responding to Segment

This section defines how you should respond to our requests.

Status Code

We use standard HTTP status code conventions to help us diagnose problems quickly and give better insight into how the destination is working.

Upon receiving data, your endpoint should reply with one of the following status codes:

CodeReason
200You’ve accepted and successfully processed the message.
202You’ve accepted the message, but have not yet processed it.
400The message is malformed, or otherwise contains an error that is the client’s fault.
401The client’s API key is malformed, or has expired or is otherwise no longer valid.
403The client’s API key is valid but has been rejected due to inadequate permissions.
500If you encounter an internal error when processing the message, reply with this code. (Hopefully you don’t have to send too many of these.)
501If we send you a call type (indicated by the type property included on all messages) you don’t support, reply with this code. Read more about the API call types we support here.
503Send us this code when your endpoint is temporarily down for maintenance or otherwise not accepting messages. This will help us to avoid dropping users’ messages during your downtime.

Response Body

You can normally send back an empty body, but when sending back a 4xx- or 5xx-class error, you may optionally send us a diagnostic message that explains the error. This message will be displayed to the user in the Segment debugger.

Be sure to send JSON (and set your Content-Type header to application/json), and send your message in the message property.

Here’s an example of a 401 response that would help a user track down why their calls aren’t appearing in your tool’s UI:

{
  "message": "API token expired"
}

Or, if your tool requires an email address in order to accept calls, this 400 reply:

{
  "message": "Missing email address"
}

3. Test your destination

Once you’ve understood the Segment data spec and the requirements above, you’re ready to start testing your destination!

The good news is we provide the test data. You can ping spec.segment.com and tell us which type of test call you want.

To retrieve a test identify call for example:

curl -H "Accept: application/json; version=2.0" \
     https://spec.segment.com/generate/identify?pretty=true

You can then send this data directly to your endpoint (be sure to replace YOUR_API_KEY with test credentials for your API):

curl -H "Accept: application/json; version=2.0" \
     https://spec.segment.com/generate/identify | \
curl -X POST \
     --user "YOUR_API_KEY:" \
     -H "Content-Type: application/json" \
     -d @- \
     http://api.your-endpoint.com/segment

4. Submit your technical survey for review

Once you’ve tested your endpoint succesfully, complete the Direct Destination Application. This is a short application that helps us gather the essentials to get you onto our platform.

Due to the high volume of requests, it may take up to a week for Segment to review your application.

5. Private Beta

After we have reviewed and approved your application and destination, you will be placed in Private Beta. The purpose of Private Beta is to test the destination with at least 10 mutual customers or more than 20MM events. You will remain in Private Beta until you have fulfilled this criteria.

When you have completed the requirements of Private Beta, you will be launched onto the platform in Public Beta. From this point on, you will be visible to all Segment customers in the dashboard!


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!