PUT

Our REST API uses the PUT method to replace resources. When using PUT, you send us a complete model of a resource, which will entirely replace the existing resource.

📘
The PUT method lets you completely replace a resource.

When replacing a resource with PUT, you may want to first view the current model of the resource, and then change all the fields you want to be different.

Example: Replacing a contact

In this example scenario, our contact at a company has been replaced with a new employee, so we'll use PUT to replace that contact in Rev.io.

1. Get the current model

First, we'll get the current model of the contact, so we can easily keep the current company and customer ID.

curl --request GET \
  --url https://restapi.rev.io/v1/Contacts/1001

Here's the response to our request:

{
  "ok":true,
  "contact_id": 1001,
  "name": "Mary Jones",
  "email": "[email protected]",
  "company": "ACME, Inc.",
  "customer_id": 1001,
  "created_date": "2015-03-05T12:18:32.35",
  "title": "Operations Team Lead",
  "fax": "5555552331",
  "mobile": "55555552332",
  "contact_type_id": 2
  "links":[
    {"rel":"self","href":"http://restapi.rev.io/v1/contacts/1001"},
    {"rel":"customer","href":"http://restapi.rev.io/v1/customers/1054"},
    {"rel":"contact-type","href":"http://restapi.rev.io/v1/contacttypes/2"}
  ]
}

We can pull the contact model from the response if we disregard the ok indicator and the links to related resources:

{
  "contact_id": 1001,
  "name": "Mary Jones",
  "email": "[email protected]",
  "company": "ACME, Inc.",
  "customer_id": 1001,
  "created_date": "2015-03-05T12:18:32.35",
  "title": "Operations Team Lead",
  "fax": "5555552331",
  "mobile": "55555552332",
  "contact_type_id": 2
}

2. Change various fields

Next, we'll take the model we received in step 1 and change it to contain the new employee's information, while leaving the company and customer ID unchanged.

{
  "contact_id": 1001,
  "name": "Janelle Miller",
  "email": "[email protected]",
  "company": "ACME, Inc.",
  "customer_id": 1001,
  "created_date": "2015-03-05T12:18:32.35",
  "title": "Operations Coordinator",
  "fax": "5555552337",
  "mobile": "55555552338",
  "contact_type_id": 2
}

3. Replace with the new model

Finally, we'll replace the current model of the contact with our new version.

curl --request PUT \
  --url https://restapi.rev.io/v1/Contacts/1001 \
  --data '{
  "contact_id": 1001,
  "name": "Janelle Miller",
  "email": "[email protected]",
  "company": "ACME, Inc.",
  "customer_id": 1001,
  "created_date": "2015-03-05T12:18:32.35",
  "title": "Operations Coordinator",
  "fax": "5555552337",
  "mobile": "55555552338",
  "contact_type_id": 2
}'

200 OK

Since we received a successful status code, we know our replacement worked and our contact has been changed.