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

Entity

An entity is the top-level structure in the Data Store, it describes something (ie a Car, a Person, an Address) with a collection of properties that hold the actual data.

Available Endpoints:

HTTP Method

Endpoint

Function

Gets all entities for a user
Creates a new entity
Partially update an entity

Gets all entities for a user

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

Retrieves all entities for a user.

Path parameters

Parameter

Required

Description

user_id
Yes
The unique id for the User.

Example request

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

Example response

HTTP/1.1 200 OK
Date: Fri, 16 Feb 2018 04:59:15 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: 361

[
    {
        "id": "24dzt2z4u3",
        "type": "person",
        "created": "2018-04-25T15:30:49.223",
        "properties": [
            {
                "id": "24dzt303lo",
                "key": "name",
                "type": "TEXT",
                "sensitive": true,
                "value": "John Doe"
            }
        ]
    }
]

Creates a new entity

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

Creates a new entity for a user.

Path parameters

Parameter

Required

Description

user_id
Yes
The unique id for the User.

Example request body

{
	"type": "person",
	"properties": [{
	    "key": "name",
	    "type": "TEXT",
	    "sensitive": true,
	    "value": "John Doe"
	}]
}

Example 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/entities/24dzt2z4u3
Content-Length: 0

Gets an entity

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

Retrieves a specific entity.

Path parameters

Parameter

Required

Description

user_id
Yes
The unique id for the User.
entity_id
Yes
The unique id for the Entity.

Example request

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

Example response

HTTP/1.1 200 OK
Date: Fri, 16 Feb 2018 04:59:15 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: 361

{
    "id": "24dzt2z4u3",
    "type": "person",
    "created": "2018-04-25T15:30:49.223",
    "properties": [
        {
            "id": "24dzt303lo",
            "key": "name",
            "type": "TEXT",
            "sensitive": true,
            "value": "John Doe"
        }
    ]
}

Replace an entity

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

Replaces an entity. This will make a complete replacement of the entity and properties, if you want to make a partial update use PATCH.

Path parameters

Parameter

Required

Description

user_id
Yes
The unique id for the User.
entity_id
Yes
The unique id for the Entity.

Example request body

{
	"type": "person",
	"properties": [{
	    "key": "name",
	    "type": "TEXT",
	    "sensitive": true,
	    "value": "John Doe's new name"
	}]
}

Example response

HTTP/1.1 204 No Content
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
Content-Length: 0

Partially update an entity

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

Makes a partial update of an entity. Use this to add new properties or change only a subset of values.

Path parameters

Parameter

Required

Description

user_id
Yes
The unique id for the User.
entity_id
Yes
The unique id for the Entity.

Example request body

{
	"type": "person",
	"properties": [{
	    "key": "name",
	    "type": "TEXT",
	    "sensitive": true,
	    "value": "John Doe's new name"
	}]
}

Example response

HTTP/1.1 204 No Content
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
Content-Length: 0

Deletes an entity

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

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

Example request

curl --request DELETE \
--url 'https://api.port.im/users/24bh0slwro/entities/24dzt2z4u3' \
--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