<access-service>/api/v1/users/me/contacts/{contactId}

URL structure

https://access-service.xy-company.com/api/v1/users/me/contacts/{contactId}

where {contactId} is the ID of a Cocoon Data user's contact.

Supported methods and overview

• PUT - modifies the an existing contact (specified by contactId) for a Cocoon Data user (whose access token is submitted in the request to this endpoint).
• DELETE - removes an existing contact (specified by contactId) or the Cocoon Data user (whose access token is submitted in the request to this endpoint).

Note: The DELETE method takes no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Modifies the email address, first name and/or last name of an existing contact (specified by contactId) that belongs to the Cocoon Data user (whose access token is submitted in the request to this endpoint).
  A contact's ID is obtained via the GET method on the <access-service>/api/v1/users/me/contacts endpoint, which retrieves a list of information for all contacts of the Cocoon Data user (whose access token is submitted in the request).
  Note: A contact's email address can be modified to one which does not match a registered Cocoon Data user account. However, if the Cocoon Data user successfully shares an item with this contact, then a new Cocoon Data user account is automatically created for this modified contact (with the Ad hoc role).
• Removes an existing contact (specified by contactId) that belongs to a Cocoon Data user (whose access token is submitted in the request to this endpoint).

Note: A contact can also be modified or removed through the Contacts feature of SafeShare for Web.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

• Originator and Collaborator - when the contact (specified by {contactId} in the request's URL) belongs to this user.

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is required if the body of the request has a JSON object:

• Content-Type: application/json

Required PUT-request parameters

The following required parameters must be sent in the body of the PUT request, as individual members of a JSON object:

• email - The email address of the contact (specified by {contactId} in the URL and belonging to the Cocoon Data user whose access token is submitted in the request to this endpoint) to be modified.
  Example (PUT request):

  {
    "email": "christina.collaborator@xy-company.com"
  }

Optional PUT-request parameters

The following optional parameters can also be sent in the body of the PUT request, each as individual members of the JSON object that includes the Required PUT-request parameters above:

• firstName - The first name of the contact (specified by {contactId} in the URL and belonging to the Cocoon Data user whose access token is submitted in the request to this endpoint) to be modified. Omitting this value in the request clears this property's value to null .
• lastName - The last name of this contact to be modified. Omitting this value in the request clears this property's value to null .
  Example (PUT request with optional parameters):

  {
    "email": "christina.collaborator@xy-company.com",
    "firstName": "Christina",
    "lastName": "Collaborator"
  }

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful PUT requests only, a JSON-formatted response containing the following members is also returned:

• id - The ID of the contact.
• email - The email address of the contact.
• firstName - The optional first name of the contact. If this value was not specified when the contact was created and/or last modified, then its value is null.
• lastName - The optional last name of the contact. If this value was not specified when the contact was created and/or last modified, then its value is also null.
• createdAt - The date and time when the contact was created.
• modifiedAt - The date and time when the contact was last modified.
  Example (response from a PUT request):

  {
      "id": "762179066710499328",
      "email": "christina.collaborator@xy-company.com",
      "firstName": "Christina",
      "lastName": "Collaborator",
      "modifiedAt": "2016-10-05T05:38:24.931Z",
      "createdAt": "2016-10-04T05:07:30.106Z"
  }