Platform Status: Good
V1.5
Join Free
API Reference
Users

Users

Your Data Subjects/Users/Customers

Available Endpoints:

HTTP Method

Endpoint

Function

Gets a list of all users
Creates a user
Gets a user
Deletes a user
Updates a user

Gets a list of all users

Endpoint URL
GET https://api.port.im/users
Content Type
application/json
Authentication
OAuth2 Access token

Retrieves users in pages of 50 rows. Paging is achieved using "offset" parameter to get the next set of 50 users. For example, to get the first 50 users call the endpoint with no offset. To get the second page of 50 users, call the endpoint with the "next" attribute returned in the last call as the offset. This allows us to deeply page through the users and iterate over the entire user base efficiently.

Parameter

Type

Required

Description

segment
String
No
The segment ID, will filter results to only users that match the segment filters
offset
String
No
The offset to start from, use the "next" value returned to get the next 50 users.

Example request

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

Example response

HTTP/1.1 200 OK
Date: Wed, 07 Feb 2018 06:37:07 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Content-Type: application/json;charset=UTF-8
Content-Length: 115

{
    "total": 100,
    "numberOfRecords": 50,
    "offset": "",
    "next": "2371jmbpq5",
    "users": [
        {
            "id": "24bh0slwro",
            "email": "customer1@domain.com",
            "name": "John Doe",
            "ref": "123455",
            "created": "2018-04-23T09:54:20.071",
            "since": "2018-04-23T09:54:20.071",
            "account": false,
            "invite_url": "https://api.port.im/signupinvite?id=24bh0slwro&token=3f24ad6c1bee89f6e6786daa85b18366f8855b7406ecc54a697395729985d250"
        }
        ...
    ]
}

Creates a user

Endpoint URL
POST https://api.port.im/users
Content Type
application/json
Authentication
OAuth2 Access token

Returns an existing user if one exists that matches either the Email Address or Ref, else creates a new one. Once created you can add data to the user with Entities. All fields are optional, posting an empty object will create a user with the name "Unknown user" and email "Unknown email". Not supplying a since date will default since to the current datetime.

Additionally, it is possible to send an array of Properties with the create user request that will emulate making a PATCH request against the first "person" entity for the user (if one doesn not exist, it will be created). This is a useful helper for putting some basic information in for the user.

Example request body

{
	"email": "customer1@domain.com",
	"name": "John Doe",
	"ref": "123455",
	"since": "2018-04-23T09:54:20.071",
	"properties": [{
	    "key": "moredata",
	    "type": "TEXT",
	    "sensitive": true,
	    "value": "Some data"
	}]
}

Example response

If a new user created you'll receive a 201 Created response.

HTTP/1.1 201 Created
Date: Wed, 07 Feb 2018 07:15:10 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Location: https://api.port.im/user/24bh0slwro
Content-Length: 0


If a matching user exists already you'll receive a 303 See Other response.

HTTP/1.1 303 See Other
Date: Wed, 07 Feb 2018 07:15:10 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Location: https://api.port.im/user/24bh0slwro
Content-Length: 0

Gets a user

Endpoint URL
GET https://api.port.im/users/{user_id}
Content Type
application/json
Authentication
OAuth2 Access token

Retrieves a specific user.

Example request

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

Example response

HTTP/1.1 200 OK
Date: Wed, 07 Feb 2018 06:37:07 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Content-Type: application/json;charset=UTF-8
Content-Length: 115

{
    "id": "24bh0slwro",
    "email": "customer1@domain.com",
    "name": "John Doe",
    "ref": "123455",
    "created": "2018-04-23T09:54:20.071",
    "since": "2018-04-23T09:54:20.071",
    "account": false,
    "invite_url": "https://api.port.im/signupinvite?id=24bh0slwro&token=3f24ad6c1bee89f6e6786daa85b18366f8855b7406ecc54a697395729985d250"
}

Deletes a user

Endpoint URL
DELETE https://api.port.im/users/{user_id}
Content Type
application/json
Authentication
OAuth2 Access token

Deletes a specific user, on success you will receive a 204 No Content response

Example request

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

Example response

HTTP/1.1 204 No Content
Date: Wed, 07 Feb 2018 06:37:07 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Content-Length: 0

Updates a user

Endpoint URL
PATCH https://api.port.im/users/{user_id}
Content Type
application/json
Authentication
OAuth2 Access token

Updates a specific user. Fields are optional - only supplied fields will be updated. On success you will receive a 303 See Other response. Note that some clients will follow the redirect.

Example request

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

Example request body

{
	"email": "customer1@domain.com",
	"name": "John Doe",
	"ref": "123455",
	"since": "2018-04-23T09:54:20.071",
}

Example response

HTTP/1.1 303 See Other
Date: Wed, 07 Feb 2018 07:15:10 GMT
Server: PORT
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
Location: https://api.port.im/user/24bh0slwro
Content-Length: 0