GraphQL Request and Response Structure
GraphQL API is an alternative to a traditional REST API, but operates similarly. To execute a query, make a POST request to the GraphQL endpoint, available at https://{MyDomainName}.my.salesforce.com/services/data/v{version}/graphql.
Replace these values:
MyDomainName: A custom subdomain specific to a Salesforce org. For example,companynamecreates the URLhttps://companyname.my.salesforce.com.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.
Request
The GraphQL request body has four parts. The query field contains the GraphQL query as a string. Optionally, use the operationName field to indicate which query to execute. Provide the operationName field if the query has multiple queries or mutations, to specify which query or mutation to execute. If the query defines any variables, include them as a map under the variables field. Finally, if the query uses extensions, include them as a map under the extensions field.
Here’s a simple request to execute a query.
1{
2 "query": "query accounts {
3 uiapi {
4 query {
5 Account {
6 edges {
7 node {
8 Id
9 Name {
10 value
11 }
12 }
13 }
14 }
15 }
16 }"
17}This request specifies that the contacts query is the one query executed of the two defined in the document.
1{
2 "query": "query accounts {
3 uiapi {
4 query {
5 Account {
6 edges {
7 node {
8 Id
9 Name {
10 value
11 }
12 }
13 }
14 }
15 }
16 }
17 query contacts {
18 uiapi {
19 query {
20 Contact {
21 edges {
22 node {
23 Id
24 Name {
25 value
26 }
27 }
28 }
29 }
30 }
31 }"
32 "operationName": "contacts"
33}This request includes argument values for variables defined in the query.
1{
2 "query": "query accountById($id: ID) {
3 uiapi {
4 query {
5 Account(where: {
6 Id: { eq: $id }
7 }) {
8 edges {
9 node {
10 Id
11 Name {
12 value
13 }
14 }
15 }
16 }
17 }
18 }",
19 "variables": {
20 "id": "001xx000003GYQxAA0"
21 }
22}Example Requests
If you’re sending a request via curl or HTTP, send the query with your API access token in a JSON string.
1curl --location --request POST 'https://lng-dev-ed.my.salesforce.com/services/data/v57.0/graphql' \
2-H 'Authorization: Bearer YourAccessToken' \
3-H 'Content-Type: application/json' \
4-d '{ "query": "query accounts { uiapi { query { Account { edges { node { Id \n Name { value } } } } } } }" }'You can also use a JSON tool like JQ to help transform or format your output.
1curl --location --request POST 'https://lng-dev-ed.my.salesforce.com/services/data/v57.0/graphql' \
2-H 'Authorization: Bearer YourAccessToken' \
3-H 'Content-Type: application/json' \
4-d '{ "query": "query accounts { uiapi { query { Account { edges { node { Id \n Name { value } } } } } } }" }' \
5| jq .To send a request via a client like Altair or Postman, pass in the query directly.
1query AllAccounts {
2 uiapi {
3 query {
4 Account {
5 edges {
6 node {
7 Id
8 Name { value }
9 }
10 }
11 }
12 }
13 }
14}Response
The response has a data section, an errors section, and an extensions section. The data section contains the response to the request query. The errors section includes errors that occur during the execution of the request. The extensions section includes extensions returned by the request.
1{
2 "data": { ... },
3 "errors": [ ... ],
4 "extensions": { ... }
5}Example Responses
If the request is successful, you receive a JSON blob like this.
1{
2 "data": {
3 "uiapi": {
4 "query": {
5 "Account": {
6 "edges": [
7 {
8 "node": {
9 "Id": "0011a000005slmbAAA",
10 "Name": {
11 "value": "GenePoint"
12 }
13 }
14 },
15 {
16 "node": {
17 "Id": "0011a000005slmcAAA",
18 "Name": {
19 "value": "United Oil & Gas, UK"
20 }
21 }
22 },
23 {
24 "node": {
25 "Id": "0011a000005slmeAAA",
26 "Name": {
27 "value": "Edge Communications"
28 }
29 }
30 }
31 ]
32 }
33 }
34 }
35 },
36 "errors": [],
37 "extensions": {}
38}If the request fails, you receive a JSON blob like this.
1{
2 "data": {},
3 "errors": [
4 {
5 "extensions": {
6 "ErrorType": "ValidationError"
7 },
8 "locations": [
9 {
10 "column": 7,
11 "line": 4
12 }
13 ],
14 "message": "Validation error of type FieldUndefined: Field 'Accounts' in type 'RecordQuery' is undefined @ 'uiapi/query/Accounts'",
15 "paths": []
16 }
17 ],
18 "extensions": {}
19}See Also
Status Codes and Error Responses
j