Concepts

Arrayables

When a query parameter has an arrayable type (e.g integer[] or string[]), many parameters may be specified, effectively resulting in an OR query.

As a practical example, if the uuid field has type string[] you may use either:

• ?uuid=2cee70ad-86cd-463f-b105-2a2989fa3425 to find a single entity with that uuid
• ?uuid[]=3e7a7ca4-c72e-49cc-9826-db585e0ed80b&uuid[]=6855273a-ab0e-4099-8145-e493e068c387 to find to entities that match those uuids

Dates

All dates on the API are in UTC, and must be provided as UTC. They're displayed in the standard ISO 8601 format. For example, December 25th 2014 at 2:25PM is 2014-12-25T14:25:00+00:00.

This format also allows us to intelligently parse intervals, and we use this for querying entities across a range of dates. Let's say you need to query all Contacts whose created_at is within the next two weeks: P2W.

• Next two weeks: P2W
• Next four and a half hours: P4H30M
• Next 3 months: P3M
• Next 2 minutes: PT2M
• Past two weeks: -P2W
• Past four and a half hours: -P4H30M
• All day on December 25th 2014: 2014-12-25T00:00:00/P1D or (2014-12-15/T24:00)
• From December 25th until December 29th: 2014-12-25/12-29 (12-29 implies the same year as the start)

Pagination

All our "list" endpoints are paginated and are supplied with metadata defining the details of the pagination.

Field	Type	Description
total	integer	Total number of results for the request
count	integer	Number of results on the current page
per_page	integer	Number of results displayed per page
current_page	integer	Number of the current requested page
total_pages	integer	Number of the total pages for the request
links	object	Object of URLs to the previous and next page
links.previous	string / undefined	URL to the previous page (If available)
links.next	string / undefined	URL of the next page (If available)

Here is an example response

{
  "data": [],
  "meta": {
    "pagination": {
      "total": 25,
      "count": 10,
      "per_page": 10,
      "current_page": 2,
      "total_pages": 3,
      "links": {
        "previous": "https://my.propertydeck.com/api/contacts?page=1",
        "next": "https://my.propertydeck.com/api/contacts?page=2"
      }
    }
  }
}

Validation

All validation failure responses will have a status code of 422 (Unprocessable Entity). Errors are grouped by the input name and may have multiple error messages

Field	Type	Description
message	string	Always "The given data was invalid."
errors	object	An object keyed by the entity attribute that failed validation

Here is an example response

{
    "message": "The given data was invalid.",
    "errors": {
        "contact.name": [
            "The name field is required."
        ],
        "contact.email": [
            "The email field is required."
        ]
    }
}

Embeddable Entities

The Property Deck API allows you to embed related entities when requesting an endpoint. Lets say you're accessing the /contacts endpoint and you also want to embed their custom fields. To do this you need to add the include query parameter. It accepts a comma-separated value containing each of the entities you want to embed in the response. To embed custom fields you would request this endpoint /contacts?embed=custom_fields.

Embedded entities are always included under the same key as the embed name (e.g ?embed=custom_fields will be embedded within custom_fields attribute on each entity). The embed has a data attribute which contains the entities you requested to embed, it may optionally contain a meta attribute.

Here is an example response

{
    "data": [
      {
        "uuid": "6b3a8994-a495-4f18-9db5-d5c0dac664a2",
        [...]
        "custom_fields": {
          "data": [
            {
              "uuid": "cc1e8607-824f-4fce-89a6-01dbd992c980",
              "name": "twitter_handle",
              "label": "Twitter",
              "type": {
                "code": 1,
                "name": "Text",
              },
              "entity_type": {
                "code": 1,
                "name": "Contact",
              },
              "value": "@PropertyDeck"
            }
          ]
        }
      }
    ]
}

Relational Filters

Some filters allow you to access attributes based on related data (e.g Contacts that have a specific status), we call these Relational Filters. You may use any of the filters that exist on the related entity.

Lets say we have a Status with the uuid 20025a25-de7a-4d9b-9d27-ee36448baa19 and we want to retrieve all Contacts with this status. We would send a GET request to /contacts?status.uuid=20025a25-de7a-4d9b-9d27-ee36448baa19.