Skip to content

Getting started with GetSocial HTTP API

The HTTP API serves two purposes:

  • Allow programmatic access to management tasks normally done on the Developer Dashboard (e.g creating apps). These endpoints require an API key.
  • Allow you to take action on behalf of a specific user (e.g creating Smart Invites). These endpoints require an access token.

This API follows the OpenAPI / Swagger 2.0 specification. Therefore, the recommended way of interacting with the API is using the official swagger-codegen tool to generate a client library for any language you prefer. This approach is the safest as it generates models and validations for all endpoints, reduces the integration work you have to do and guarantees compatibility with the API.

That said, this is still just an HTTP API and you can make requests directly instead.

API Reference

You can find the API reference and a web client here. You can also use the spec to generate your own client.

API Keys

API keys are used for management endpoints and are meant as a programmatic alternative for the Developer Dashboard. They allow you to manage apps, Smart Links and more.

Creating an API Key

  1. On the Developer Dashboard, go to API Keys on the Account Settings dropdown:


    API Keys

  2. Click New API Key. Here you can give a name to the API key (for your reference) and choose permissions.


    New API Key

  3. Choose permissions. There are 2 levels: Full and Limited.

    • Keys with Full permissions will have access to all apps under your account. Full is also required to create new apps.
    • By choosing Limited, you can select which apps the API key will access to. We recommend using separate keys for each app for security purposes.

  4. Configure IP whitelist (optional). By default, there are no restrictions on which IP addresses you can make requests from. If you’d like to restrict access, you can enter any valid IPv4 or IPv6 range in CIDR notation.

  5. Once you are satisfied with the configuration, click Create.


    API Key Created

Managing API Keys

You can manage all API keys from the Developer Dashboard.

Example Request

Once you have created an API key, you can make requests with it. Here’s a request for getting a list of all apps that the key has access to:

curl -X GET \
  https://api.getsocial.im/v1/apps \
  -H 'Accept: application/json' \
  -H 'X-GetSocial-API-Key: f456a945256fed9b2a48436715b412e9'

Response:

[
    {
        "icon": "https://example.com/icon.png",
        "id": "example",
        "name": "Example App",
        "platforms": {
            "android_settings": {
                "cert_fingerprints": [
                    "example"
                ],
                "enabled": false,
                "package_name": "com.my.app"
            },
            "ios_settings": {
                "app_store_id": "12345",
                "bundle_id": "com.my.app",
                "enabled": false,
                "team_id": "EXAMPLE"
            }
        }
    }
]

Access Tokens

Access tokens belong to specific users of your app and allow you to take action on behalf of them, like creating a Smart Invite.

Acquiring an Access Token

Access tokens are acquired via the user authentication endpoint.

Example Request

Request:

$ curl -X POST "https://api.getsocial.im/v1/authenticate/user?app_id=${app_id}&identity_type=email&value=user%40example.com&token=${API_KEY}" \
  -H "accept: application/json"

Response:

{
  "access_token": "c2Vzc2lvbjp1OjE2ODY3ZTZlLTBkOGYtNDg1OC1iNmFjLTQ0OTk0MDk0NDE1NA==",
  "user": {
    "id": "186037659029290536",
    "identities": {
      "email": "user@example.com"
    },
    "name": "User 5756536"
  }
}

Expiration

Access tokens expire 1 hour after last use. When expired, any request made with that token will return an HTTP 401 Unauthorized error. In that case, simply authenticate again to get a new token.

Making Requests

Use the X-GetSocial-Access-Token header to make user authenticated requests.

Example Request

For example, here is a request for referral processing, where a user has arrived on your website from a Smart Link and you’d like to attribute that signup to GetSocial.

Request:

curl -X GET "https://api.getsocial.im/v1/referral/process?url=https%3A%2F%2Fmyapp.gsc.im&2Ffg78hn4e5&new_user=true" \
     -H "accept: application/json" \
     -H "X-GetSocial-Access-Token: c2Vzc2lvbjp1OjE2ODY3ZTZlLTBkOGYtNDg1OC1iNmFjLTQ0OTk0MDk0NDE1NA=="

Response:

{
  "data": {
    "source": "website",
    "foo": "baz",
    "$guaranteed_match": "true"
  },
  "original_data": {
    "foo": "bar"
  },
  "referrer": {
    "id": "123",
    "name": "User 123",
    "picture": "https://cdn.example.com/pictures/user123.png",
    "identities": {
      "email": "hello@example.com"
    }
  }
}

Web Client & curl Commands

The API Reference includes a client that can be used to make requests. You can also get an equivalent curl command from the response.


Example Request

Rate Limiting

The HTTP API is subject to various rate limits intended to prevent abuse and ensure availability. Regular API usage should not trigger these limits, but if it does and you believe you were limited in error, please contact us for a limit increase.

If you are rate limited, all API endpoints will return HTTP 429 Too Many Requests.

Give us your feedback! Was this article helpful?

😀 🙁