Working with Contact Relationships

Introduction

Actionstep provide a feature to manage relationships between contacts. This is useful for tracking relationships between clients, contacts, and other entities in your system. For example, you might want to track that a client is the spouse of another client, or that a contact is the parent of a child. The contactrelationships endpoint allow you to create and manage these relationships using the Actionstep API.

In this tutorial, we will explore how to work with contact relationships. We will cover the following topics:

1. Retrieving contact relationships
2. Creating a new contact relationship
3. Updating a contact relationship
4. Deleting a contact relationship

Viewing Contact Relationships in Actionstep

When you edit a contact record in Actionstep you will see a section called "Relationships" towards the bottom of the page. This section lists all the relationships that have been created for that contact (if any). From here you can create either a forward relationship or a reverse relationship.

Retrieving Contact Relationships

To retrieve the list of all contact relationships make a GET request to the contactrelationships endpoint.

GET {{base_url}}/api/rest/contactrelationships

...
{
    "id": "Father--41845--343217",
    "relationship": "Father",
    "links": {
        "fromContact": "41845",
        "toContact": "343217"
    }
},
...

You can filter contact relationships based on the relationship, fromContact, or toContact properties, or a combination of all three. For example:

GET {{base_url}}/api/rest/contactrelationships?relationship=Father

GET {{base_url}}/api/rest/contactrelationships?fromContact=41845

GET {{base_url}}/api/rest/contactrelationships?toContact=343217

GET {{base_url}}/api/rest/contactrelationships?relationship=Father&fromContact=41845&toContact=343217

To retrieve an individual contact relationship record use the unique identifier of the relationship in the request URL. For example:

GET {{base_url}}/api/rest/contactrelationships/Father--41845--343217

Creating a Contact Relationship

To create a new contact relationship, you need to specify the fromContact, toContact, and relationship properties in the request body.

POST {{base_url}}/api/rest/contactrelationships

{
    "contactrelationships": {
        "relationship": "Father",
        "links": {
            "fromContact": "41845",
            "toContact": "340412"
        }
    }
}

The direction of a relationship is based on the contact from which you are defining the relationship. The way to think about this is to imagine you are editing a contact record using the Actionstep web interface.

In a forward relationship the contact from which you are defining the relationship is the fromContact and the contact to which you are defining the relationship is the toContact. The reverse is true for a reverse relationship.

A forward relationship created from contact 41845 to contact 340412 would be shown as a reverse relationship when viewing the relationship from contact 340412.

For example, viewing the relationship from contact 41845 would show the relationship as a forward relationship to contact 340412.

Viewing the relationship from contact 340412 would show the same relationship as a reverse relationship to contact 41845.

NB: You can provide a relationship type that contains space characters, for example, "Temporary Guardian". The contactrelationships endpoint handles this correctly and allows you to return the relationship record using a GET request. For example:

GET {{base_url}}/api/rest/contactrelationships/Temporary%20Guardian--41845--343217

Updating a Contact Relationship

There is not explicit PUT or PATCH endpoint for updating a contact relationship. To update a contact relationship you need to delete the existing relationship and create a new one.

Deleting a Contact Relationship

To remove a relationship between two contacts (in either direction), you make a DELETE request and specify the relationship record's unique identifier.

DELETE {{base_url}}/api/rest/contactrelationships/Father--41845--343217