The CertCapture API has the ability to save or attach related data whenever you do a POST or PUT request. The way the save is handled is based of what type of relationship occurs between the data (we will get to this later).

Associating Related Data

If you wish to save or associate some related data via an update request, just supply the information via the request.

PUT
URL: /v2/exposure-zones/1
DATA: {
    country={
        "id": 1
        "name": "United States"
        "initials": "US"
    }
}

The above PUT request to /v2/exposure-zones/1/ would update Exposure Zone 1 to have the country United States. As long as the below criteria is met:

1. The country relationship is a valid for the current model and it's not a read only relationship.

2. The country data provided is valid and exists.

(`United States` exists with `id` of `1` and `initials` of `US`.)

Both of the below requests are also valid when associating a country:

PUT
URL: /v2/exposure-zones/1
DATA: {
    country = {
      "id": 1
    }
}

And:

PUT
URL: /v2/exposure-zones/1
DATA: {
    country={
        "name": "United States"
        "initials": "US"
    }
}

CertCapture will look at ALL the data provided for country and see if it can find a single matching result, before assigning it to an Exposure Zone.

Unassociating Related Data

To remove an existing data relationship, simply pass that relationship with null

PUT
URL: /v2/exposure-zones/1
DATA: {
    country = null
}

Or

PUT
URL: /v2/exposure-zones/1
DATA: {
    country=
}

NOTE: Removing an association will NOT remove the related entity.

Associating Non-Existent Data

If you wish to associate a relationship with something that doesn't exist yet, the API call will fail. You will need to create it manually via the API endpoint, then do the association.

NOTE: This is not the case for One to Many relationships. One to Many relationships will ALWAYS create a new entity before associating it.

Associated Many Relationships

Some relationships are not able to be modified via a POST or PUT request on a normal resource. These are usually for relationships that are One to Many or Many to Many and there are specific API endpoints to handle them.

One to Many

Associating an entity with a one to many relationship:

PUT
URL: /v2/customers/1/log
DATA: {
  logs = [{
    "account": "Account Name",
    "entry": "Updated customer Information"
  }]
}

The above request would CREATE a log for Customer 1, as long as the below criteria is met:

1. Each log data provided is valid.

Removing a many to many entity association:

DELETE
URL: /v2/customers/1/log/
DATA: {
    logs = [{ "id": 10 }]
}

The above request would DELETE the Log, as long as the below criteria is met:

1. The log data provided is valid and the relationship exists.

Many to Many

Associating an entity with a many to many relationship:

PUT
URL: /v2/certificates/1/customers
DATA: {
    customers = [{ "id": 10 }, { "id": 20 }]
}

The above request would associate Customer 10 and Customer 20 with Certificate 1, as long as the below criteria is met:

1. Each customer data provided is valid and exists.

Removing a many to many entity association:

DELETE
URL: /v2/certificates/1/customers/
DATA: {
    customers = [{ "id": 10 }]
}

The above request would remove the associate of Customer 10 with Certificate 1, as long as the below criteria is met:

1. The customer data provided is valid and the relationship exists.

NOTE: Removing an association will NOT remove the related entity.

Many to Many Pivot Data

Some Many to Many relationships have pivot data, E.G. Customer 1 has a Custom Field 10 with a value of custom field value

If you wish to update the value of that, simply do the same action as you would if you were assigning a Many to Many relationship, and pass in the updated value field.

PUT
URL: /v2/customers/1/custom-fields/
DATA: {
    custom_fields = { "id": 10, "value": "update my customer custom field value!" }
}