4me GraphQL API

The 4me GraphQL API allows to create precise and flexible queries for the data you need to integrate with 4me, getting predictable results.

For a general introduction to the GraphQL query language please see https://graphql.org.

Service URL

The 4me GraphQL API has a single point of entry:

https://graphql.4me.com/

The endpoint remains constant no matter what operation you perform.

All query and mutation requests to the 4me GraphQL API must use the HTTP POST method. The request body should specify exactly which operation is to be used.

Please note the use of https:// in the URL above. All communication is encrypted over HTTPS. Non-secure requests are rejected, so we recommend establishing a test connection with the secure API entry point before sending sensitive data.

Authentication

The 4me GraphQL API requires an OAuth token for making authenticated requests.

You can obtain an OAuth token either by generating a Personal Access Token from My Profile in 4me, or by creating an OAuth Application from the Settings console in 4me.

Each request to the 4me GraphQL API must supply two HTTP headers:

The 4me account ID value passed in the X-4me-Account header determines the current account that the API request will use. The view current_account, which is the default view for most root-connection queries, limits results to records in the given current account.

A personal access token can be generated in the 4me Specialists console by going to 'My Profile' and then selecting the 'Personal Access Tokens' section from the menu. Make sure to add sufficient permissions to the token by adding the scopes required by your API requests. To perform queries the 'Read' action should be allowed on the model matching the node types of the collections accessed. Mutations require either the 'Create' or 'Update' action for their model.

Example request:

    $ curl -H "Authorization: Bearer cgbb2rhPCMHSE...SQxXkjYBzNOPzx" \
           -H "X-4me-Account: widget" \
           -H "Content-Type: application/json" \
           -X POST \
           -d '{"query": "{ me { id name } }"}' \
           https://graphql.4me.com/

Response:

    {"data":{"me":{"id":"NG1lLmNvbS9QZXJzb24vNg","name":"Howard Tanner"}}

Note that for this example to work your OAuth token must have added a scope to allow action Me - Name or Me - Profile or me - All.

Root Types

The functionality of a GraphQL API is described by its schema. Every GraphQL schema has a root type for both queries and mutations.

The query type defines how GraphQL operations reads data. It is analogous to performing HTTP GET, but sent using POST.

The mutation type defines how GraphQL operations change data. It is analogous to performing HTTP methods such as POST, PATCH, and DELETE. The various mutation types supported in the GraphQL API are all sent using POST. The other HTTP methods are not used.

Introspection

The 4me GraphQL API is introspective. This means you can ask the 4me GraphQL schema for details about itself. A schema defines a GraphQL API's type system, providing information about what queries and mutations it supports. Reqests from API clients are validated and executed against the schema.

For example, query __schema to list all types defined in the schema:

    query {
      __schema {
        types {
          name
          kind
          description
          fields {
            name
          }
        }
      }
    }

Query __type to get details about a single type:

    query {
      __type(name: "ServiceLevelAgreement") {
        name
        kind
        description
        fields {
          name
        }
      }
    }

It is also possible to retrieve the complete schema via a simple GET request:

$ curl -H "Authorization: bearer <oauth-token>" https://graphql.4me.com/

Note: The introspection query is the only time a GET request (and no X-4me-Account header) is accepted. When sending a request body, the request method is POST, whether it is a query or a mutation.

Global Node IDs

Node is a generic term for an object or record. You can look up a node directly, or you can access related nodes via a connection. Each node is identified by a global node ID. In GraphQL it is the id field of type ID on the node interface. In the response of a 4me REST API request it is the nodeID field. In 4me Webhook payloads they are the fields that end with _nodeID in their name.

A node ID in 4me is globally unique across systems.

Given a node ID, to find the object type in GraphQL, post for example this query:

    query {
      node(id: "NG1lLmNvbS9QZXJzb24vNg") {
        __typename
      }
    }

The response might look like:

    {
      "data": {
        "node": {
          "__typename": "Person"
        }
      }
    }

Knowing the type of the node an inline fragment can be used to query the details of the node:

    query {
      node(id: "NG1lLmNvbS9QZXJzb24vNg") {
        ... on Person {
          name
          primaryEmail
        }
      }
    }

The response might look like:

    {
      "data": {
        "node": {
          "name": "Howard Tanner",
          "primaryEmail": "howard.tanner@widget.com"
        }
      }
    }