SObject Relationships

Accesses records by traversing object relationships via friendly URLs. You can retrieve, update, or delete the record associated with the traversed relationship field. If there are multiple related records, you can retrieve the complete set of associated records. This resource is available in REST API version 36.0 and later.

URI

/vXX.X/sobjects/SObject/id/relationship field name

Formats

JSON, XML

HTTP Methods

GET, PATCH, DELETE

Authentication

Authorization: Bearer token

Parameters

Parameter	Description
fields	Optional for GET. A list of fields in the associated relationship record to return. Fields are separated by commas. For example: `1/services/data/v36.0/sobjects/SObject/id/relationship field?fields=field1,field2`

Response Body

For retrievals via GET, the response body is the contents of the record associated with the relationship field. Here is 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.

1https://yourInstance.salesforce.com/services/data/v49.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r

1{
2    "attributes" : 
3    { 
4        "type" : "Distributor__c",
5        "url" : "/services/data/v36.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}

A response body isn’t returned for updates via PATCH and deletions via DELETE.

Error Responses

If no record is 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.

Example

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

REST API Developer Guide

SObject Relationships