Attach and Detach Operations
You can use the attach and detach operations to define or remove a relationship between two record instances. For example, you can associate a contact record instance with a partner record instance, or a file record instance with an opportunity record instance.
Currently, you can attach or detach contact records and file records only.
Attach and detach operations are defined using the !attach and !detach actions as part of the URL in the record REST service, which is called through the POST HTTP method. In the request body, you can specify optional attachment attributes for the attach operation, such as setting the role for attaching a contact. The request body can be empty if no optional attachment attributes are set. The content type of the request body is application/json.
To attach or detach two records, the record type and IDs of the record instances are required. All this information is part of the URL. The record type and ID of the instance to which the record is being attached or detached are defined after the version specification. The record type and ID of the record instance being attached or detached are defined following the operation identifier.
For example:
.../services/rest/record/v1/customer/660/!attach/contact/106
The only optional parameter set in the request body is role, which you can set when attaching a contact record.
Sample Code
The following sections show the usage of the attach and detach operations.
Attaching Records
The following example shows how to attach a contact record instance to a customer record instance.
POST .../services/rest/record/v1/customer/660/!attach/contact/106
Content-Type: application/json
{
"role": {
"id": "-10"
}
}
or
empty body or {}
The following example shows how to attach a file record instance to an opportunity record instance.
POST .../services/rest/record/v1/opportunity/379/!attach/file/398
empty body
The attach and detach operations also support the usage of external IDs, as shown in the following example.
POST .../services/rest/record/v1/customer/eid:JOHN_DOE42/!attach/contact/eid:user1
Content-Type: application/json
{
"role": {
"externalId": "family"
}
}
Successful requests return the HTTP 204 No Content response.
Detaching Records
The URL structure for the detach operation must be constructed in a way that you first specify the record type and record instance ID after the v1 API version from which you are detaching a record instance.
Then, the record type and record instance ID that you are detaching is specified at the end of the URL.
The following example shows how to detach a contact record instance from a customer record instance.
POST .../services/rest/record/v1/customer/660/!detach/contact/106
empty body
The following example shows how to detach a file record instance from an opportunity record instance.
POST .../services/rest/record/v1/opportunity/379/!detach/file/398
empty body
Successful requests return the HTTP 204 No Content response.