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.

Get Records Using sObject Relationships

Gets a record based on the specified object, record ID, and relationship field. The fields and field values of the record are returned in the response body. If there are multiple related records, you can retrieve the complete set of associated records.

If there’s no record associated with a relationship field, a 404 error response is returned. If the relationship field normally resolves to multiple records and no relationship set exists, a 200 response is returned. If the fields parameter is used with fields that don’t exist or aren’t visible to the consumer by field-level security, a 400 error response is returned. For other error messages, see Status Codes and Error Responses.

Syntax

URI: /services/data/vXX.X/sobjects/sObject/id/relationshipFieldName

Formats: JSON, XML

HTTP Method: GET

Authentication: Authorization: Bearer token

Parameters

Parameter	Description
sObject	The name of the object. For example, `Account`.
id	The identifier of the record. For example, `001R0000005hDFYIA2`.
relationshipFieldName	The name of the field that contains the relationship. For example, `Opportunities`.
fields	Optional for GET. A comma-delimited list of fields in the associated relationship record returned in the response body.

Example fields:

1/services/data/v67.0/sobjects/sObject/id/relationship field?fields=field1,field2

Example

For examples of using sObject Relationships to access relationship fields, see Traverse Relationships with Friendly URLs.

Example Request

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

Example Response Body

The response body is the contents of the record associated with the relationship field. Here’s an example of a request and JSON response body for a simple relationship traversal that returns the Distributor__c record associated with a relationship field on custom object Merchandise__c.

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}

REST API Developer Guide

Get Records Using sObject Relationships

Syntax

Example

See Also