API Resource: Entities

Heads up! MonkeyPod's API is only available to Enterprise users and requires significant technical expertise to use. The API is considered to be in "beta" and remains under active development. We will make reasonable efforts to ensure its stability, but make no guarantees, warranties, or promises with respect to its availability or performance. 

Entities represent what are generally called "relationships" in MonkeyPod. They are the people (or companies, agencies, etc.) with whom your organization interacts.

There are four supported endpoints for entities:

  1. Retrieve a single entity
  2. Create an entity
  3. Update an entity
  4. Delete/deactivate an entity 

Entity resources are accessible at: 

https://[YOUR-SUBDOMAIN].monkeypod.io/api/v2/entities/[ENDPOINT]

Retrieve a Single Entity

Method: GET

Endpoint: /[ENTITY-ID]

Sample request:

GET https://my-org.monkeypod.io/api/v2/entities/960a735b-3ee9-4440-9c6d-25cbf27c77fe

Sample response:

{
  "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
  "resource": "entity",
  "data":{
    "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
    "type": "Individual",
    "honorific": "Ms.",
    "first_name": "Jane",
    "middle_name": "Q.",
    "last_name": "Smith",
    "pronouns": "she/her/they",
    "aliases": [
      "Jane the Great"
    ],
    "title": "CEO",
    "organization_name": "Jane's Awesome Business",
    "website": "https://example.com",
    "email": "jane.q.smith@example.com",
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "99999-9999",
    "country": "United States",
    "extra_attributes": {
      "alma-mater": "Stanford University",
      "favorite-color": "blue"
    },
    "created_at": "2022-05-16T18:38:31.000000Z",
    "updated_at": "2022-05-16T18:38:31.000000Z",
    "phones": [
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951c",
        "type": "Home",
        "number": "888-555-1212"
      },
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951d",
        "type": "Cell",
        "number": "999-666-2323"
      }
    ],
    "roles": [
      "Customer",
      "Donor"
    ]
  }
}

Create an Entity

Method: POST

Endpoint: /

Input validation:

  • Required fields are: 
    • type (one of "Individual", "Organization", "Foundation", "Corporate", "Government", or "Other"
    • last_name or email (if type is "Individual")
    • organization_name (if type is not "Individual")
  • If you provide extra_attributes, each hash key must match a "slug" value of an existing Custom Attribute in MonkeyPod, and the values provided must be valid for the corresponding Custom Attribute.
  • If you provide roles, each array element must match an existing Relationship Role in MonkeyPod.

Sample request:

POST https://my-org.monkeypod.io/api/v2/entities
{
  "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
  "type": "Individual",
  "honorific": "Ms.",
  "first_name": "Jane",
  "middle_name": "Q.",
  "last_name": "Smith",
  "pronouns": "she/her/they",
  "aliases": [
    "Jane the Great"
  ],
  "title": "CEO",
  "organization_name": "Jane's Awesome Business",
  "website": "https://example.com",
  "email": "jane.q.smith@example.com",
  "address": "123 Main Street",
  "city": "Anytown",
  "state": "CA",
  "postal_code": "99999-9999",
  "country": "United States",
  "extra_attributes": {
    "alma-mater": "Stanford University",
    "favorite-color": "blue"
  },
  "phones": [
    {
      "type": "Home",
      "number": "888-555-1212"
    },
    {
      "type": "Cell",
      "number": "999-666-2323"
    }
  ],
  "roles": [
    "Customer",
    "Donor"
  ]
}

Sample response:

{
  "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
  "resource": "entity",
  "data":{
    "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
    "type": "Individual",
    "honorific": "Ms.",
    "first_name": "Jane",
    "middle_name": "Q.",
    "last_name": "Smith",
    "pronouns": "she/her/they",
    "aliases": [
      "Jane the Great"
    ],
    "title": "CEO",
    "organization_name": "Jane's Awesome Business",
    "website": "https://example.com",
    "email": "jane.q.smith@example.com",
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "99999-9999",
    "country": "United States",
    "extra_attributes": {
      "alma-mater": "Stanford University",
      "favorite-color": "blue"
    },
    "created_at": "2022-05-16T18:38:31.000000Z",
    "updated_at": "2022-05-16T18:38:31.000000Z",
    "phones": [
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951c",
        "type": "Home",
        "number": "888-555-1212"
      },
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951d",
        "type": "Cell",
        "number": "999-666-2323"
      }
    ],
    "roles": [
      "Customer",
      "Donor"
    ]
  }
}

Update an Entity

Method: PUT

Endpoint: /[ENTITY-ID]

Input validation:

  • Only the attributes provided will be updated. Missing attributes will be ignored.
  • Custom Attributes ("extra_attributes"):
    • If you provide extra_attributes, each hash key must match a "slug" value of an existing Custom Attribute in MonkeyPod, and the values provided must be valid for the corresponding Custom Attribute.
    • Custom attributes not included in the extra_attributes hash will be ignored and unchanged. To delete a particular custom attribute value, include its slug as a hash key with a null value.
  • Roles:
    • If you provide roles, each array element must match an existing Relationship Role in MonkeyPod.
    • If the "roles" key is included in your request, then the entity's roles will be completely replaced by the list provided.
  • Phones:
    • Although phones are nested as part of an entity resource's JSON representation, phones are not directly modifiable in an entity update request. If you include the "phones" key in your request JSON, it will be ignored. Instead, you may update or delete each phone individually in a separate API request using the phone's unique ID. 

Sample request:

PUT https://my-org.monkeypod.io/api/v2/entities/960a735b-3ee9-4440-9c6d-25cbf27c77fe
{
  "honorific": "Mrs.",
  "last_name": "Jones"
}

Sample response:

{
  "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
  "resource": "entity",
  "data":{
    "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
    "type": "Individual",
    "honorific": "Mrs.",
    "first_name": "Jane",
    "middle_name": "Q.",
    "last_name": "Jones",
    "pronouns": "she/her/they",
    "aliases": [
      "Jane the Great"
    ],
    "title": "CEO",
    "organization_name": "Jane's Awesome Business",
    "website": "https://example.com",
    "email": "jane.q.smith@example.com",
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "99999-9999",
    "country": "United States",
    "extra_attributes": {
      "alma-mater": "Stanford University",
      "favorite-color": "blue"
    },
    "created_at": "2022-05-16T18:38:31.000000Z",
    "updated_at": "2022-05-16T18:38:31.000000Z",
    "phones": [
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951c",
        "type": "Home",
        "number": "888-555-1212"
      },
      {
        "id": "96508708-ba4b-4b92-b577-e6ee7cdf951d",
        "type": "Cell",
        "number": "999-666-2323"
      }
    ],
    "roles": [
      "Customer",
      "Donor"
    ]
  }
}

Delete (or Deactivate) an Entity

Method: DELETE

Endpoint: https://[YOUR-SUBDOMAIN].monkeypod.io/api/v2/entities/[ENTITY-ID]

Note:

  • Entities that are necessary for data integrity purposes (e.g., because they appear on one or more transactions, etc.) may not be deleted. They will be deactivated instead.

Sample request:

DELETE https://my-org.monkeypod.io/api/v2/entities/960a735b-3ee9-4440-9c6d-25cbf27c77fe

Successful delete requests respond with HTTP status code 204 and an empty response body.

Delete requests that result in deactivation will respond as if an update request had been issued instead.