GraphQL Request and Response Structure

The GraphQL API is an alternative to a traditional REST API, but operates in a similar way. To execute a query, make a POST request to the GraphQL endpoint, available at https://[your_instance].salesforce.com/services/data/{{version}}/graphql. For a collection of sample queries, see our Postman Collection. For a deep dive into the types involved in the request and response, see the API Reference.

The GraphQL request body is composed of three parts. The GraphQL query document is embedded in the request as a string, under the field named query. Which query to execute is indicated by the optional operationName field. This field must be provided if the query document has multiple queries or mutations, to specify which query or mutation to execute. Finally, if the query defines any variables then include them as a map under the variables field.

Here's a simple request to execute a query.

This request specifies that the contacts query is the one query executed of the two defined in the document.

This request includes argument values for variables defined in the query.

The response is composed of a data section and an errors section. The data section contains the response to the requests query. Any errors that occur during the execution of the request are included in the errors section.