Platform Status: Good
V1.5
Join Free

Get Started with the PORT API

Before You Start

The PORT API is designed for developers who are comfortable creating custom-coded solutions or integrating with RESTful APIs.

The API allows you to push users and their data into PORT using the API and synchronise events from PORT with Webhooks. Building an App will allow you to register Data Sources in the PORT service that can be used in the PORT compliance tools by your team.

PORT Data Model

The PORT platform introduces some terms and concepts you may not be familiar with. These elements form the underlying basis of how PORT works.

Data Source

Provides data into the platform. Data Sources are provided by Apps.

Data Agreement

Describes a set of compliance attributes: Lawful basis for processing data, purposes for processing data, whom the data is shared with and where it is stored.

Entity

A top level data object stored against a user that could represent anything, such as a "person", "property" or "vechicle". Entities are made up of many Properties.

Grant

Links a user to a Data Agreement, holding the status of the relationship.

Property

A property is a typed key/value that stores data and belongs to an entity. An example might be firstname/joe that belongs to a "person" Entity.

Schema

Schemas describe the structure of Entities and Properties. PORT provides a common root schema that shares common data structures across Apps, but allows Apps to build their own schemas where they want to store custom datasets.

User

A Data Subject... more commonly known as your customers/users.

Authentication

The API uses OAuth2 access tokens to authenticate requests. You can generate API access tokens in Your Setup.

Example request

Use the Authorization header to deliver the Access Token as part of a Bearer token.

curl --request GET \
--url 'https://api.port.im/' \
--header 'Authorization: Bearer {access_token}' \
--include

Resources

Resources are typically nouns like 'users' or 'events' that you can take actions on using supported HTTP verbs. The root path for the API includes a map of all available resources:

https://api.port.im

JSON

The PORT API uses JSON to serialise data in requests and responses. Where possible there will be examples of output in the API Reference.

HTTP Methods

Where possible, the API strives to use appropriate HTTP methods for interacting with resources.

HTTP Method

Description

GET
Retrieve a resource.
POST
Create new resource
PATCH
Update a resource. With PATCH requests you only need to provide the data you want to change.
PUT
Replace a resource.
DELETE
Remove a resouce.

HTTP Response Codes

The API uses HTTP response codes to indicate the status of operation performed. The response could be a HTTP Redirect, clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Response Code

Description

200
Operation successful.
201
Resource created. The location of the resource created is specified in the Location header field
204
No content. Operation was successful, but there is no content to return (often used after a DELETE call)
400
Bad request. Invalid parameters or payload.
404
Resource not found.
422
Unprocessable Entity. Validation failed.

Date Formats

The API uses the ISO 8601 Date Time format. Example:

2018-02-15T14:00:34.62Z