API Guide

REST API #

The Phleb-Finders’ Portal is a single page application so a frontend uses REST API to connect with a backend. All operations you perform using UI, you can implement via API calls using your programing language.

Most of API functions return JSON. POST and PUT requests usually need some data passed in the payload in JSON format.

Requests needs to have the header: Content-Type: application/json.

The path to the API is: api/v1/.

Example of GET API request:

GET https://phlebfindersportal.com/api/v1/Contact/{uniqueID}

In this documentation we omit the site URL and api/v1/ path when we show examples of API functions. If you utilize any our client implementation, it will prepend these parts automatically.

Note: API client implementations (available below) do most of work for you: add needed headers, handle autentication, parameters, etc.

Authentication #

Authentication by Api Key #

You will be required to get an API User login. This will be made on request/need.

Authentication header:

X-Api-Key: API_KEY_COPIED_FROM_THE_USER_DETAIL_VIEW

Authentication Token / User Specific Data #

GET App/user

Make this request to retrieve an access token.

Returns:

  • token – access token to use
  • acl – information about user access
  • preferences – user preferences
  • user – user record attributes

Error codes #

400 Bad request #

When you create or update a recod, this error can mean that you didn’t pass a required field or it has an empty value. Check the response message or see data/log for more details.

403 Forbidden #

Usually occurs when you don’t have an access to a specific record or action. See data/log for more details.

404 Not found #

Usually occurs when a requested record doesn’t exist.

API :: CRUD Operations #

List #

GET {entityType}

Returns a list of records of a specific entity type.

GET parameters:

  • maxSize – (int) max size
  • offset – (int) offset
  • where – (array) filters
  • orderBy – (string) attribute to sort by
  • order – (string: ‘asc’ | ‘desc’) sort direction
  • select – (string) list of attributes to be returned, sepratated by comma; if not specified, then all attributes will be returned; whitespaces are not allowed

Example:

GET Account?offset=0&maxSize=20

Returns:

{
  "list": [... array of records...],
  "total": {totalCountOfRecords}
}

See more info about search parameters.

Read #

GET {entityType}/{id}

Returns attributes of a specific record.

Example:

GET Account/5564764442a6d024c

Create #

POST {entityType}

Creates a new record of a specific entity type.

Payload: Object of entity attributes.

Returns attributes of the created record.

Example:

POST Account

Payload:

{
  "name": "Test",
  "assignedUserId": "1"
}

Update #

PUT {entityType}/{id}

Updates an existing record.

Payload: Object of entity attributes needed to be changed.

Returns attributes of the updated record.

Example:

PUT Account/5564764442a6d024c

Payload:

{
  "assignedUserId": "1"
}

Delete #

DELETE {entityType}/{id}

Deletes an existing record.

Returns TRUE if success.

Example:

DELETE Account/5564764442a6d024c

API :: Related records #

GET {entityType}/{id}/{link}

GET parameters:

  • maxSize – (int) max size
  • offset – (int) offset
  • where – (array) filters
  • orderBy – (string) attribute to sort by
  • order – (string: ‘asc’ | ‘desc’) sort direction
  • select – (string) list of attributes to be returned, sepratated by comma; if not specified, then all fields will be returned

You can find more info about search params here.

Example:

GET Account/5564764442a6d024c/opportunities

Returns:

{
  "list": [... array of records...],
  "total": {totalCountOfRecords}
}

See more info about search parameters.

POST {entityType}/{id}/{link}

Relates two records.

Payload:

  • id – ID of the record to relate with
  • ids – array of IDs of the records to relate with
  • massRelate – optional, false or true, whether to use search criteria that will be used instead of specific ids
  • where – optional search criteria

Example:

POST Account/5564764442a6d024c/opportunities

Payload:

{
  "id": "55646fd85955c28c5"
}

DELETE {entityType}/{id}/{link}

Unrelates two records.

Payload fields:

  • id – ID of related record to remove
  • ids – array of IDs of related records to remove

Example:

DELETE Account/5564764442a6d024c/opportunities

Payload:

{
  "id": "55646fd85955c28c5"
}

API :: Stream #

List stream records for the current user #

GET Stream

Get parameters:

  • offset – (int) offset
  • maxSize – (int) max size

List stream notes of a specific record #

GET {entityType}/{id}/stream

Get parameters:

  • offset – (int) offset
  • maxSize – (int) max size

Follow record #

PUT {entityType}/{id}/subscription

Unfollow record #

DELETE {entityType}/{id}/subscription

Post to stream #

POST Note

Payload attributes:

  • type – should be the string value Post
  • parentId – ID of the record to post to
  • parentType – entity type of the record to post to
  • post – text to post
  • attachmentsIds – optional, array of IDs of attachments (should be uploaded in separate request beforehand)

Payload example:

{
  "type": "Post",
  "parentId": "someId",
  "parentType": "Case",
  "post": "This is a test\n\nHello"
}

API :: Attachment #

Uploading #

POST Attachment

  • Method: POST
  • Action: Attachment
  • Headers: Content-Type: application/json

Payload attributes:

  • name – file name;
  • type – mime type;
  • role – specify value Attachment;
  • relatedType – entity type attachment is related to (only for fields of File type);
  • relatedId – record ID attachment is related to (only for fields of File type);
  • parentType – entity type attachment is related to (only for fields of Attachment Multiple type);
  • field – field name of related record attachment is related through;
  • file – file contents.

Note: parentId attribute is available when uploading and will be ignored.

Example (File field) #

The attachment to be stored in the field of File type.

STEP 1. UPLOAD ATTACHMENT #

POST Attachment

{
    "name": "test.txt",
    "type": "text/plain",
    "role": "Attachment",
    "relatedType": "Document",
    "field": "file",
    "file": "data:text/plain;base64,FILE_CONTENTS_ENCODED_WITH_BASE64"
}

Returns attachment record attributes:

{
    "id": "{some-id}",
    "name": "test.txt"
}
STEP 2. SET ATTACHMENT ID IN RELATED RECORD #

Then you need to send the 2nd request that creates (or updates) the Document record. You will need to fill fileId attribute with ID returned after POST Attachment request.

Create:

POST Document

{
    "name": "document-name",
    "fileId": "{id-of-attachment}"
}

Update:

PUT Document/{document-id}

{
    "fileId": "{id-of-attachment}"
}

Example (Attachment-Multiple field) #

STEP 1. UPLOAD ATTACHMENT #

The attachment to be stored in the field of Attachment-Multiple type.

POST Attachment

{
    "name": "test.txt",
    "type": "text/plain",
    "role": "Attachment",
    "parentType": "Note",
    "field": "attachments",
    "file": "data:text/plain;base64,FILE_CONTENTS_ENCODED_WITH_BASE64"
}
STEP 2. SET ATTACHMENT ID IN PARENT RECORD #

Then you need to send the 2nd request that creates (or updates) the parent Note record. You need to specify attachmentsIds attribute with an array that contains ID returned after POST Attachment request.

Create:

POST Note

{
    "post": "Some text",
    "type": "Post",
    "attachmnetsIds": ["{id-of-attachment}"]
}

Update:

PUT Note/{id-of-note-record}

{
    "attachmnetsIds": ["{id-of-attachment}"]
}

Note: If you are attaching to an existing record, you need also to add current attachments, otherwise they will be unlinked from the record.

Downloading #

GET Attachment/file/{id}

Where {id} is an ID of the attachment record.

Returns attachment contents.

API :: Account #

List #

GET Account #

Returns a list of accounts and total number of records. It’s possible to specify filters.

Requires read access to Account scope.

Example:

GET Account?select=name&maxSize=2&orderBy=name&order=asc

will return:

{
    "list": [
        {
            "id": "someId1",
            "name": "Test 1"
        },
        {
            "id": "someId2",
            "name": "Test 2"
        }
    ],
    "total": 2100
}

Create #

POST Account #

Creates an account. Returns its attributes.

Requires create access to Account scope.

Payload: Record attributes.

Example:

POST Account

with payload:

{
    "name": "Test",
    "assignedUserId": "someUserId"
}

Read #

GET Account/{id} #

Returns attributes of a specific Account record.

Requires read access to Account record.

Example:

GET Account/someId

with return:

{
    "id": "someId",
    "name": "Test",
    "createdById": "someUserId",
    "createdByName": "Some Name",
    "assignedUserId": "someUserId",
    "assignedUserName": "someName",
    "teamsIds": [],
    "teamsNames": {}
}

Update #

PUT Account/{id} #

Updates an existing Account. Returns its attributes.

Requires edit access to Account record.

Payload: Record attributes.

Example:

PUT Account/someId

with payload:

{
    "assignedUserId": "someUserId"
}

Delete #

DELETE Account/{id} #

Removes an existing account.

Returns TRUE if success.

Requires delete access to Account record.

Example:

DELETE Account/someId

Stream #

GET Account/{id}/stream #

Returns stream records of a specific account.

GET parameters: maxSizelimit.

Requires stream access to Account record.

Relationships #

Returns a list of related records linked through link relation and their total number of records. It’s possible to specify filters.

GET parameters are available here.

Requires read access to Account record and read access to the scope of the related entity type.

POST Account/{id}/{link} #

Relate an existing account with a specific record (or multiple records) throuh a specific link.

Requires edit access to Account record and edit access to the scope of the related entity type.

Payload parameters are available here.

Unlinks a specific record, linked throgh a specific link, from an account.

Requires edit access to Account record and edit access to the scope of the related entity type.

Payload:

  1. JSON with id string attribute
  2. JSON with ids array attribute

Powered by BetterDocs