| Developer Portal

Help Center

Firstup API Guidance

This document provides information about concepts and behaviors that apply broadly across the API.

Security and Scalability

The Firstup system is designed to be horizontally scalable allowing large numbers of concurrent users to use the platform with no impact on availability, consistency, or performance. The platform follows scalability best practices, ensuring that performance and availability adhere to system SLAs regardless of user load.

All customer data must be encrypted in transmission from and to customer facing applications using industry standard AES-256 bit encryption.

Our security practices include:

A detailed overview of the Firstup security and operational policies is available in our Operational Excellence document (contact Firstup at info@socialchorus.com for a copy).

Resource Representation

Data Types

Response properties of similar types use conventions in both their key and value formatting.

Requests

Endpoints are accessed at https://partner.socialchorus.com/v2/.

All requests must use the HTTPS protocol. This ensures that all information transferred between client and server is encrypted and protected.

Up to 1,000 requests are allowed per minute per program.

Authentication

All requests must provide an Authorization header as defined by the Authentication and Authorization section of these docs. The bearer token format used by the OAuth standard is:

Authorization: Bearer <ACCESS TOKEN>

Where <ACCESS TOKEN> is replaced with an access token for the acting user.

For example:

curl -H "Authorization: Bearer <ACCESS TOKEN>" 'https://partner.socialchorus.com/v2/content'

If OAuth requirements are not met, 401 (user not found or not identified based on access token in request) and 403 (user permission) responses are returned. (Refer to the “Client Errors” section for more details.)

Verbs and Routes

Endpoints in the Firstup Partner API use RESTful URLs and request methods in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the route and methods expected, but the following describes the typical operations you can expect to encounter:

PUT operations are generally idempotent actions, meaning that making the request twice will have no different effect than calling it once. Calling a POST request twice, on the other hand, can be expected to create two records.

Endpoints will often identify the record being operated against in the URL itself. For example, a URL that describes a content post will use the RESTful URL format GET /v2/channels/123 where “123” is the ID of the channel record.

Furthermore, entities or resources nested within a parent resource will also typically be identified in the URL. A list of content within a channel would be represented as GET /v2/channels/123/content; and a specific content record within a channel, as GET /v2/channels/123/content/456. These are broad patterns used in the API and each endpoint will specify the URL to use.

Sorting

Some endpoints provide the ability to sort the returned records. Usually these are endpoints that list records, such as an endpoint for listing all channels or for listing the users in the program.

Endpoints allowing sorting will always use the same ?sort=<parameter> query to declare the intended sort order. The parameters by which an endpoint can be sorted will be listed in that endpoint’s documentation.

Sorting is in ascending order by default, but can be inverted to descending order using a “-” character in front of the parameter name. For example, ?sort=-title sorts the records by title in descending order, with a record titled “Zoo” listed before a record titled “Animal”.

Multiple sort parameters can also be provided using a comma as delimiter between parameter names. The query ?sort=title,created_at will sort the records by title, and for any records with the same title, the created_at property will then determine the order in which they’re returned.

Attempting to sort by a parameter not supported by a given endpoint can be expected to return a 400 Bad Request response.

Filtering

Some endpoints allow filtering of returned items; these are endpoints that return top-level collections of data and statistics-related requests. Requested filters must be formatted as a dictionary within the filter parameter.

By default, filters are enum-based (for example, “published|archived|draft”), where items that match the filter are exact matches to the provided filter value. When possible, endpoints allow for filtering items by any property provided in the resource. Exceptions apply for cases such as long text properties.

Resources with timestamp properties offer range-based filters including .from and .to. Timestamp filters accept either timestamps (2018-05-01T17:36:52) or datestamps (2018-05-01) in ISO 8601 format. Datestamp values are assumed to be in UTC.

Example filters where created_at is a resource property:

When multiple filters are used in a single request, the filters are combined using intersection. Specifying the filters foo=1&amp;bar=2 yields items that have a foo value of ‘1’ and a bar value of ‘2’ (“this AND that”; not “this OR that”).

When a filter allows for multiple values to be matched, values can be provided as a list, using either a comma-delimited string or an array of strings. Filters that allow for multiple values by default operate in a “match ANY” behavior. Specify the filter foo=bar,baz will yield items that either have a foo value of “bar” or “baz”. Endpoint filters that use a different behavior will specify their behavior in the documentation.

Filter values provided in a request that cannot be parsed or do not match expected formats result in a 400 Bad Request response.

Pagination

Many endpoints that return top-level collections of data allow for pagination of returned items. The requested page specification must be formatted as a dictionary within the page parameter.

Page number can be provided as page.number and defaults to 1. Page size can be provided as page.size. Each endpoint specifies its own default page size.

For endpoints that provide feed-based pagination, page cursors can be provided as page.cursor. The cursor value to use can be fetched from the previous request. In the following example, "cursor" represents the cursor used on the current request, "next" represents the cursor to use for the next request.

{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "example-current-cursor-value",
      "next": "example-next-cursor-value",
      "page_size": 10
    }
  }
}

Pagination values provided in a request that cannot be coerced or that exceed specified ranges result in a 400 Bad Request response.

Pagination values that request ranges not available (for example, requesting page 4 when there is only enough data for 3 pages) will respond with an empty data set and pagination metadata showing that the requested page is out of range.

Responses

Responses in the Firstup Partner API use RESTful response bodies in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the responses and errors expected, but this section describes the typical responses you can expect to encounter.

Response Headers

Every response provides the following special response headers:

Response Body

Endpoints that return data will always wrap that data in a “data” property, whether the response data is a dictionary or array.

Success Responses

Successful responses that return data always wrap their data in a “data” property and include a “meta” object at the root level when meta information is available (Refer to the Metadata section for details).

While different endpoints use different response codes that correspond to the purpose and design of the endpoint, the following are general patterns you can expect:

Each endpoint will describe the response statuses it returns.

Metadata

Every successful response provides metadata relating to the response in the root of the response body. The meta property includes information that helps to explain the aspects that went into determining what data to return in the response, including pagination, filtering, and sorting.

For endpoints that allow pagination, the metadata includes a pagination property. The page property includes values used in pagination even if the request did not specify a page.

For endpoints that use page pagination, the following properties are provided:

For endpoints that use cursor pagination, the following properties are provided:

For endpoints that allow filtering, the metadata includes a filters property. The filters property includes default values used in filtering even if the request did not specify filters. For example, if a filter such as “status” is set to “registered” by default, the filter’s property will include status: “registered”.

For endpoints that allow __searches, the metadata includes a search property that indicates the value of the search param used in the request. If the search property was reformatted or transformed in any way, it will be represented in the meta properties in its transformed format.

For endpoints that allow sorting, the metadata includes a sort property that indicates the list of sort keys used in order.

Error Responses

All errors (4xx and 5xx) response bodies will be wrapped in an “error” structure containing the following fields:

For example:

{
  "error": {
    "code": 403,
    "title": "Unauthorized Access",
    "detail": "<Message about authorization>"
  }
}

Some errors include additional data fields containing information about the error. For example, a validation error will contain a validations field as shown below:

{
  "error": {
    "code": 400,
    "title": "Bad Request",
    "detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.",
    "validations": [
      {
        "code": "required",
        "detail": "Title is required",
        "parameter": "title"
      }
    ]
  }
}

Client Error Codes

Error codes in the range 400 - 499 indicate invalid input or improper use of the API. Clients should alter their request to correct the indicated error before trying the request again.

Status Code Description
400 Bad Request: A request parameter or formatting does not match an expected required format. Typical cases include:
  • Missing a required parameter
  • Invalid formatting of a parameter, such as providing a timestamp filter where the parameter value cannot be coerced to a date or time
  • Page number or size is not in valid range
Validation errors include an additional `validations` parameter that contains an array of validation entries specific to individual parameters in the request. Each entry has the following format:
  • code
  • detail
  • parameter
401 Unauthenticated: Returned when a required access token is not provided. See “Authentication and Authorization” for details.
403 Forbidden: The Authenticated User does not have permissions required to perform the action requested.
404 Not Found: Returned when a primary resource is not found. A primary resource can be defined as resource scoped in the URL of the endpoint. For example, the URL channels/123/content/456 results in 404 if the channel or the content doesn't exist, or if the content exists but is not associated to the channel. Additionally, requests for contextually private resources may return 404 as a way to avoid revealing the presence of the resource.
409 Conflict: Returned by some endpoints when attempting to use or update an identifier that is already taken by another record in that collection.
429 Too Many Requests: Returned when the rate limit is exceeded. The rate limit is 1,000 requests per minute, per program. A delay and a retry is recommended.

Server Error Codes

Error codes in the range 500 - 599 indicate an error on the server. Clients should retry their request again later, or contact support for assistance.

Status Code Description
500 Internal server error
504 Request timeout

Documentation