This section covers what you need to get basic integration working with your third-party app. See the API Authentication for more information on authentication.

Accounts

These endpoints let a user find the available accounts that can be used by this token.

List Accounts

GET /api/v1/accounts.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single account’s details

GET /api/v1/accounts/1.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Projects

These endpoints give the token access to whatever the user that produced the token has access.

List Projects

GET /api/v1/projects.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single project’s details

GET /api/v1/projects/1.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Lists

Lists are manually added collections of mentions, people, or companies.

Get the project’s lists

GET /api/v1/projects/1/lists.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single project list’s details

GET /api/v1/projects/1/lists/1.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a paginated list of the items that are on the list

GET /api/v1/projects/1/lists/1/items.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single item (mention, parent) from a list.

GET /api/v1/projects/1/lists/1/items/234546.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Segments

Segments are essentially saved advanced searches. They contain mentions, people, or companies.

Get the project’s segments

GET /api/v1/projects/1/segments.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single project segments’s details

GET /api/v1/projects/1/segments/1.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a paginated list of the items that are in the segment.

GET /api/v1/projects/1/segments/1/items.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

View a single item (mention, parent) from a segment.

GET /api/v1/projects/1/segments/1/items/234546.json HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Options

Options is a path on the API that will return lists of options that you can select. These are built for integration into their party applications like Integromat. But, they can be super helpful to make your third party application as easy to use as possible.

Using the options path, you can get a list of segments, or lists that are available to your API token across projects.

In all of the cases, you will receive back an array of hashes that have the following format:

{
  "label": "Name of the item", 
  "value": 32 # the id of the item
}

Get a list of segments available to you to configure as options.

GET /api/v1/options.json&type=segments HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a list of the lists available to you to configure as options.

GET /api/v1/options.json&type=lists HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a list of the projects available to you to configure as options.

GET /api/v1/options.json&type=projects HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a list of the keywords available to you to configure as options.

GET /api/v1/options.json&type=keywords HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Get a list of the accounts available to you to configure as options.

GET /api/v1/options.json&type=accounts HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

Selects

Options allow you to select aomething that provides values. Often, you want to pull 1 field from this item (such as a list of Twitter accounts). To do this, you can use the “selects” API path. This path will return just 1 field from the list of items.

For example, let’s say you’ve created a segment of twitter mentions. You can retriever profile friendly name that contains the Twitter profile that produced the mention.

Using the options path, you can get a list of segments, or lists that are available to your API token across projects.

In all of the cases, you will receive back an array of hashes that have the following format:

[{
  "{{field_name}}": "field_value", 
}]

The query parameters that MUST to be passed to the select are, for example, for lists:

GET /api/v1/options.json&type=lists&id={{list_id}}&field={{field_name}} HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

# type, id, and field

So, if you have a list with the id of 25456 and you want the profile_friendly_id of the items on that list, you’d query:

GET /api/v1/options.json&type=lists&id=25456&field=profile_friendly_id HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

# type, id, and field

The system supports a 4th parameter, filter, that can be used to filter the list items returned. This will search in the value being returned and only return items that include this text.

Let’s say in the example above you ONLY want Twitter profile IDs. You can add the filter to only return Twitter Ids.

GET /api/v1/options.json&type=lists&id=25456&field=profile_friendly_id&filter=twitter HTTP/1.1
Authorization: Bearer Mj4RBjNKH2bkCMDGREPdih29
Connection: close

# type, id, and field

This will match values like twitter/profile:wef3 but not values like facebook/profile:wflanagan.

Conclusion

Our goal with the API is to make the API as easy to use and integrate into your third party tools as possible. Should there be something you need or want, please let us know and we’ll be happy to add it to make your job easier!