Getting Started

The GraphQL API is the primary way for third-party applications to read and write to the Worksome platform.

New to APIs? Start with What is an API? for a beginner-friendly overview. Coming from REST? See Coming from REST? for a quick comparison. For GraphQL terminology, read the full Introduction to GraphQL guide.

To get started, you’ll need an API access token, you can learn about and generate one from the Authentication page. Once you’ve generated a token, carry on reading to learn how to use the API.

We also have extensive documentation for the API available on Apollo Studio, which is searchable and may be easier to use.

The GraphQL Endpoint

The GraphQL API has a single endpoint:

https://api.worksome.com/graphql

The endpoint is constant no matter what operation you perform.

This endpoint also functions as a GraphQL explorer, using the official GraphiQL interface. This can be used to test GraphQL queries or use introspection to discover the API.

Making your first request

GraphQL requests to our API are made over HTTP, via the POST request method. All data is sent in JavaScript Object Notation (JSON) format.

We’ll be creating a GraphQL API request using the Laravel HTTP Client for this example.

use Illuminate\Support\Facades\Http;

$apiToken = env('WORKSOME_API_TOKEN');

// The query is a GraphQL structured request specifying what is needed.
$query = <<<GQL
    query {
      viewer {
        name
        email
      }
    }
GQL;

// If necessary, variables can also be provided to the query.
$variables = [];

$response = Http::withToken($apiToken)
    ->post('https://api.worksome.com/graphql', [
        'query' => $query,
        'variables' => $variables,
    ])
    ->json();

dd($response);

curl -X POST https://api.worksome.com/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ viewer { id name } }",
    "variables": {}
  }'

JavaScript

const response = await fetch('https://api.worksome.com/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '{ viewer { id name } }',
    variables: {},
  }),
});

const { data, errors } = await response.json();

Discover your accounts

Most API operations require a company context. After authenticating, query the viewer for your user info and the top-level accounts field for the accounts you can act on. accounts returns an Account interface — use a fragment (e.g., ... on Company) to read company-specific fields:

{
  viewer {
    id
    name
    email
  }
  accounts {
    id
    name
    ... on Company {
      market
    }
  }
}

{
  "data": {
    "viewer": {
      "id": "VXNlcjoxMjM0",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "accounts": [
      {
        "id": "Q29tcGFueTox",
        "name": "Acme Corp",
        "market": "UK"
      },
      {
        "id": "Q29tcGFueToy",
        "name": "Acme Corp (Staging)",
        "market": "UK"
      }
    ]
  }
}

Use the account id as the company identifier when creating hires, jobs, or other company-scoped operations. The Account interface is implemented by Company, Organisation, Partner, StaffingAgency, and Worker — pass the right kind of ID for the operation you are calling (most company-context operations require a Company ID).