Creating BAAs and DPAs that use underlying agreements

Some of our standards are meant to be associated with other agreements (usually a CSA). We refer to these as underlying agreements and they're specific to agreements and not normally set at the the template. This means they need to be set when you send out an agreement via our web app or the API.

Creating a BAA and specifying an underlying agreement

There are two ways to specify an underlying agreement via the API. Add a baa_attributes or dpa_attributes object to your json request and set underlying_agreement_type to internal. Then specify the agreement's id with underlying_agreement_id.

Curl example using an internal underlying agreement

Code
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_UUID",
    "owner_email": "ben@example.org",
    "signer_email": "ben@example.org",
    "agreement": {
      "recipient_name": "Ben Garvey",
      "recipient_email": "someone@example.org",
      "recipient_organization": "Test co",
      "message": "This is the agreement we spoke about.",
      "test_agreement": false,
      "baa_attributes": {
        "underlying_agreement_type": "internal",
        "underlying_agreement_val": null,
        "underlying_agreement_id": "AGREEMENT_UUID"
      }
    }
  }'

Curl example using an external underlying agreement

The second way to set the underlying agreement is via the external type. Add a baa_attributes or dpa_attributes object to your json request and set underlying_agreement_type to external. Then describe the underlying agreement using the underlying_agreement_val field. It should be descriptive enough so there is no doubt over which agreement you're referring to.

Code
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_UUID",
    "owner_email": "ben@example.org",
    "signer_email": "ben@example.org",
    "agreement": {
      "recipient_name": "Ben Garvey",
      "recipient_email": "someone@example.org",
      "recipient_organization": "Test co",
      "message": "This is the agreement we spoke about.",
      "test_agreement": false,
      "baa_attributes": {
        "underlying_agreement_type": "external",
        "underlying_agreement_val": "CSA signed with XYZ Corp on September 15, 2024",
        "underlying_agreement_id": null
      }
    }
  }'

Curl example for a DPA

DPAs work the same way under dpa_attributes. With internal, underlying_agreement_id must be the id of a CSA in Common Paper. This example uses an external agreement and also overrides two of the DPA template's defaults.

Code
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "DPA_TEMPLATE_UUID",
    "owner_email": "ben@example.org",
    "signer_email": "ben@example.org",
    "agreement": {
      "recipient_name": "Ben Garvey",
      "recipient_email": "someone@example.org",
      "recipient_organization": "Test co",
      "dpa_attributes": {
        "underlying_agreement_type": "external",
        "underlying_agreement_val": "CSA signed with XYZ Corp on September 15, 2024",
        "include_governing_country_eu_val": "Ireland",
        "include_provider_security_contact_email_val": "security@example.org"
      }
    }
  }'

Fields you leave out of dpa_attributes keep the template's values. See Template Parameters for every DPA field.