GraphQL Request and Response Structure

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://{MyDomainName}{version}/graphql.

Replace these values:

  • MyDomainName: A custom subdomain specific to a Salesforce org. For example, companyname creates the URL
  • version: A Salesforce API version in the format XX.X. For example, 57.0.

For a collection of sample queries, connect to the Salesforce Developer 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.

If you're sending a request via curl or HTTP, send the query with your API access token in a JSON string.

You can also use a JSON tool like JQ to help transform or format your output.

To send a request via a client like Altair or Postman, pass in the query directly.

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.

If the request is successful, you receive a JSON blob like this.

If the request fails, you receive a JSON blob like this.

Status Codes and Error Responses