Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Traverse Relationships with Friendly URLs

You can traverse relationship fields in standard and custom objects by constructing friendly URLs using the sObject Relationship resource. This approach allows you to directly access records associated by relationships. Using friendly URLs is an easier alternative to accessing records by obtaining object IDs from relationship fields and then inspecting the associated object ID record.

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

Relationship names follow certain conventions that depend on the direction (parent to child, or child to parent) of the relationship and the name of the related object. The conventions are described in Understanding Relationship Names in the SOQL and SOSL Reference.

There are limits to the number of relationship traversals you can make in a single REST API call. These limits are the same as the limits for SOQL, as described in Understanding Relationship Query Limitations in the SOQL and SOSL Reference. Keep the following limitations in mind when traversing relationships.

When specifying child-to-parent relationships, no more than five levels can be traversed. The following traverses two child-to-parent relationships.
1https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/ChildOfChild__c/record id/Child__r/ParentOfChild__r
When specifying parent-to-child relationships, no more than one level can be traversed. The following traverses one parent-to-child relationship.
1https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/ParentOfChild__c/record id/Child__r

Traversing Standard Objects

The standard object Contact contains a relationship field to the Account standard object. The following example retrieves the Account record related to a Contact record.

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Contact/0035e00000PiemmAAB/Account -H "Authorization: Bearer token"

Example request body for traversing a standard object relationship: none required

Example response body for traversing a standard object simple relationship

1{
2    "attributes": {
3        "type": "Account",
4        "url": "/services/data/v67.0/sobjects/Account/0015e00000TwULCAA3"
5    },
6    "Id": "0015e00000TwULCAA3",
7    "IsDeleted": false,
8    "Name": "relationshipAccountName",
9    "PhotoUrl": "/services/images/photo/0015e00000TwULCAA3",
10    "OwnerId": "0055e000003E8ooAAC",
11    "CreatedDate": "2021-11-06T17:38:40.000+0000",
12    "CreatedById": "0055e000003E8ooAAC",
13    "LastModifiedDate": "2021-11-06T17:38:40.000+0000",
14    "LastModifiedById": "0055e000003E8ooAAC",
15    "SystemModstamp": "2021-11-06T17:38:40.000+0000",
16    "LastActivityDate": null,
17    "LastViewedDate": "2021-11-06T17:40:50.000+0000",
18    "LastReferencedDate": "2021-11-06T17:40:50.000+0000"
19}

Example of traversing a simple relationship

This custom object named Merchandise__c contains a lookup relationship field to a child Distributor__c custom object. The following example retrieves the Distributor__c record related to a Merchandise__c record.

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r -H "Authorization: Bearer token"

Example request body for traversing a simple relationship: none required

Example response body for traversing a simple relationship

1{
2    "attributes" : 
3    { 
4        "type" : "Distributor__c",
5        "url" : "/services/data/v67.0/sobjects/Distributor__c/a03D0000003DUhcIAG"
6    },
7    "Id" : "a03D0000003DUhcIAG",
8    "OwnerId" : "005D0000001KyEIIA0",
9    "IsDeleted" : false,
10    "Name" : "Distributor1",
11    "CreatedDate" : "2011-12-16T17:43:01.000+0000",
12    "CreatedById" : "005D0000001KyEIIA0",
13    "LastModifiedDate" : "2011-12-16T17:43:01.000+0000",
14    "LastModifiedById" : "005D0000001KyEIIA0",
15    "SystemModstamp" : "2011-12-16T17:43:01.000+0000",
16    "Location__c" : "San Francisco"
17}

If no related record is associated with the relationship name, the REST API call fails, because the relationship can’t be traversed. Using the previous example, if the Distributor__c field in the Merchandise__c record was set to null, the GET call would return a 404 error response.

You can traverse multiple relationships within the same relationship hierarchy in a single REST API call as long as you don’t exceed the relationship query limits. If a Line_Item__c custom object is the child in a relationship to a Merchandise__c custom object, and Merchandise__c also has a child Distributor__c custom object, you can access the Distributor__c record starting from the Line_Item__c record using something like the following.

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Line_Item__c/a02D0000006YL7XIAW/Merchandise__r/Distributor__r -H "Authorization: Bearer token"

Relationship traversal also supports PATCH and DELETE methods for relationships that resolve to a single record. Using the PATCH method, you can update the related record.

Example of using PATCH to update a relationship record

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r -H "Authorization: Bearer token"  -d @update_info.json -X PATCH

Example JSON request body for updating a relationship record contained in update_info.json

1{
2    "Location__c" : "New York"
3}

Example response body for updating relationship record: none returned

Finally, using the DELETE method, you can delete the related record.

Example using DELETE to delete a relationship record

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r -H "Authorization: Bearer token" -X DELETE

Example request body for deleting a relationship record: none required

Example response body for update relationship record: none returned

Traversing Relationships with Multiple Records

You can traverse relationships with multiple records, and get a response that contains the set of records. For relationships that resolve to multiple records, only GET methods are supported.

Example traversing a relationship with multiple records

If we have a custom object named Merchandise__c that contains a master—detail relationship field to a Line_Item__c custom object, the following example retrieves the set of Line_Item__c records related to a Merchandise__c record.

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Line_Items__r -H "Authorization: Bearer token"

Example request body for traversing a relationship with multiple records: none required

Example response body for traversing a relationship with multiple records

For this example, two Line_Item__c records were retrieved.

1{
2    "done" : true,
3    "totalSize" : 2,
4    "records" :
5    [
6        {
7            "attributes" :
8            {
9                "type" : "Line_Item__c",
10                "url" : "/services/data/v67.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"
11            },
12            "Id" : "a02D0000006YL7XIAW",
13            "IsDeleted" : false,
14            "Name" : "LineItem1",
15            "CreatedDate" : "2011-12-16T17:44:07.000+0000",
16            "CreatedById" : "005D0000001KyEIIA0",
17            "LastModifiedDate" : "2011-12-16T17:44:07.000+0000",
18            "LastModifiedById" : "005D0000001KyEIIA0",
19            "SystemModstamp" : "2011-12-16T17:44:07.000+0000",
20            "Unit_Price__c" : 9.75,
21            "Units_Sold__c" : 10.0,
22            "Merchandise__c" : "a00D0000008oLnXIAU",
23            "Invoice_Statement__c" : "a01D000000D85hkIAB"
24        },
25        {
26            "attributes" :
27            {
28                "type" : "Line_Item__c",
29                "url" : "/services/data/v67.0/sobjects/Line_Item__c/a02D0000006YL7YIAW"
30            },
31            "Id" : "a02D0000006YL7YIAW",
32            "IsDeleted" : false,
33            "Name" : "LineItem2",
34            "CreatedDate" : "2011-12-16T18:53:59.000+0000",
35            "CreatedById" : "005D0000001KyEIIA0",
36            "LastModifiedDate" : "2011-12-16T18:53:59.000+0000",
37            "LastModifiedById" : "005D0000001KyEIIA0",
38            "SystemModstamp" : "2011-12-16T18:54:00.000+0000",
39            "Unit_Price__c" : 8.5,
40            "Units_Sold__c" : 8.0,
41            "Merchandise__c" : "a00D0000008oLnXIAU",
42            "Invoice_Statement__c" : "a01D000000D85hkIAB"
43        }
44    ]
45}

The serialized structure for the result data is the same format as result data from executing a SOQL query via REST API. See Query for more details on executing SOQL queries via REST API

If no related records are associated with the relationship name, the REST API call returns a 200 response with no record data in the response body. This result is in contrast to the results when traversing an empty relationship to a single record, which returns a 404 error response. This behavior is because the single record case resolves to a REST resource that can be used with PATCH or DELETE methods. In contrast, the multiple record case can only be queried.

If an initial GET request for a relationship with multiple records returns only part of the results, the end of the response contains the field nextRecordsUrl. For example, you could get a field like the following at the end of your response.

1"nextRecordsUrl" : "/services/data/v67.0/query/01gD0000002HU6KIAW-2000"

You can request the next batch of records using the provided URL with your instance and session information, and repeat until all records have been retrieved. These requests use nextRecordsUrl and don’t include any parameters. The final batch of records doesn’t have a nextRecordsUrl field.

Example usage for retrieving the remaining results

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/query/01gD0000002HU6KIAW-2000 -H "Authorization: Bearer token"

Example request body for retrieving the remaining results: none required

Example response body for retrieving the remaining results

1{
2    "done" : true,
3    "totalSize" : 3200,
4    "records" : [...]
5}

Filtering Result Fields

When retrieving records via relationship traversals, you can optionally specify only a subset of the record fields be returned by using the fields parameter. Multiple fields are separated by commas. The following example retrieves just the Location__c field from the Distributor__c record associated with a Merchandise__c record:

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r?fields=Location__c -H "Authorization: Bearer token"

The JSON response data would look like the following:

1{
2    "attributes" :
3    {
4        "type" : "Distributor__c",
5        "url" : "/services/data/v67.0/sobjects/Distributor__c/a03D0000003DUhhIAG"
6    },
7    "Location__c" : "Chicago",
8}

Similarly, for requests that result in multiple records, you can use a list of fields to specify the fields returned in the record set. For example, assume you have a relationship that was associated with two Line_Item__c records. You want just the Name and Units_Sold__c fields from those records. You could use the following call.

1curl https://MyDomainName.my.salesforce.com/services/data/v67.0/sobjects/Merchandise__c/a01D000000INjVe/Line_Items__r?fields=Name,Units_Sold__c -H "Authorization: Bearer token"

The response data would look like the following.

1{
2    "done" : true,
3    "totalSize" : 2,
4    "records" : 
5    [
6        {
7            "attributes" :
8            {
9                "type" : "Line_Item__c",
10                "url" : "/services/data/v67.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"
11            },
12            "Name" : "LineItem1",
13            "Units_Sold__c" : 10.0
14        },
15        {
16            "attributes" :
17            {
18                "type" : "Line_Item__c",
19                "url" : "/services/data/v67.0/sobjects/Line_Item__c/a02D0000006YL7YIAW"
20            },
21            "Name" : "LineItem2",
22            "Units_Sold__c" : 8.0
23        }
24    ]
25}

If any field listed in the fields parameter set isn’t visible to the active user, the REST API call fails. In the previous example, if the Units_Sold_c field was hidden from the active user by field-level security, the call would return a 400 error response.

REST API Developer Guide

Traverse Relationships with Friendly URLs

Traversing Standard Objects

Traversing Relationships with Multiple Records

Filtering Result Fields