Getting Started
Basic Concepts
Tutorials
Advanced Concepts
How-to Guides
Building integration flows
Data transformation
Integration patterns
Developing Components
Tenant Management
Components
CRM Components
ERP Components
E-Commerce Components
Basic Components
Utility Components
References
Sailor
Component Descriptor
Covered in this article

Managing Contracts

This document provides information on Contract management, namely the following actions: creating Contracts, retrieving Contract data, editing Contract memberships, editing Contracts.

Creating Contracts

A Contract is an enclosed environment, which contains Workspaces and DevTeams. A Tenant member with the corresponding permissions can create Contracts in their Tenant via the following request:

POST /v2/contracts

Below are request parameters:

Payload Parameter Required Description
type yes Allowed value: contract
attributes.name yes Name of the new Contract
attributes.available_roles[] no A subset of the Tenant’s roles.

EXAMPLE:

To create a new contract, we will use the following request:

curl /v2/contracts \
  -X POST \
  -u {EMAIL}:{APIKEY} \
  -H 'Content-Type: application/json' -d '
      {
       "data":{
         "type":"contract",
         "attributes":{
           "name":"My Contract",
           "available_roles":[
             {
               "scope":"contracts",
               "role":"admin"
             },
             {
               "scope":"workspaces",
               "role":"admin"
             }
           ]
         }
       }
     }'

NOTE: Contract name is limited by usable characters and length. It may contain only letters, digits, whitespaces, - and _ symbols, and be from 3 to 40 symbols long.

Getting Contract Data

With the right permissions a Contract member can get Contract data via the API. Namely, the following actions are available:

1. Get Contract by ID via the following request:

GET /v2/contracts/CONTRACT_ID/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID
include no Parameter for getting more detailed information regarding the Contract’s entities. Allowed values: members and/or invites.

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}?include=members,invites \
   -u {EMAIL}:{APIKEY}

2. Get Contracts via the following request:

GET /v2/contracts/

EXAMPLE:

curl /v2/contracts/
  -u {EMAIL}:{APIKEY}

2. Get a list of Contract members via the following request:

GET /v2/contracts/CONTRACT_ID/members/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/members/ \
  -u {EMAIL}:{APIKEY}

3. Get a list of pending invites via the following request:

GET /v2/contracts/CONTRACT_ID/invites/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/invites/ \
   -u {EMAIL}:{APIKEY}

4. Get Contract roles via the following request:

GET /v2/contracts/CONTRACT_ID/roles/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/roles/ \
  -u {EMAIL}:{APIKEY}

Editing Contract Memberships

A Contract member with the corresponding permissions can:

1. Invite a user to the Contract via the following request:

POST /v2/contracts/{CONTRACT_ID}/invites/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID
Payload Parameter Required Description
type yes Allowed value: contract-invite
attributes.email yes Email
attributes.roles[] yes Roles. To get all available roles, please execute the “Get the Contract’s roles” endpoint.
attributes.workspace_id no Corresponding Workspace ID for cases when you want to invite a user into a Contract and a Workspace.
attributes.workspace_roles no (yes, if Workspace ID was specified) To get all available roles, please execute the “Get the Contract’s roles” endpoint.

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/invites/ \
    -X POST \
    -u {EMAIL}:{APIKEY} \
    -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "contract-invite",
           "attributes": {
               "email": "admin@email.com",
               "roles": [
                 "owner"
               ],
               "workspace_id":"{WORKSPACE_ID}",
               "workspace_roles":[
                 "integrator"
               ]
           }
       }
    }'

2. Add a new member to the Contract via the following request:

POST /v2/contracts/{CONTRACT_ID}/members

Below are request parameters:

Payload Parameter Required Description
ID yes ID of a registered Tenant user.
type yes Allowed value: contract-member
attributes.roles[] yes Roles. To get all available roles, please execute the “Get the Contract’s roles” endpoint.

3. Update membership in the contract via the following request:

PATCH /v2/contracts/{CONTRACT_ID}/members/{USER_ID}/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID
USER_ID yes Target user ID
Payload Parameter Required Description
type yes Allowed value: contract-member
id yes ID of a registered user. Must match the USER_ID URL parameter.
attributes.roles[] yes To get all available roles, please execute the “Get the Contract’s roles” endpoint.
     

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/members/{USER_ID}/ \
    -X PATCH  \
    -u {EMAIL}:{APIKEY} \
    -H 'Content-Type: application/json' -d '
    {
       "data": {
           "type": "contract-member",
           "id": "{USER_ID}",
           "attributes": {
               "roles": [
                 "{NEW_ROLE}"
               ]
           }
       }
    }'

4. Remove a user from a contract via the following request:

DELETE /v2/contracts/{CONTRACT_ID}/members/{USER_ID}/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID
USER_ID yes Target user ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/members/{USER_ID}/ \
   -X DELETE    \
   -u {EMAIL}:{APIKEY}

IMPORTANT:

  • If a contract only has one member, which is the Owner, it is still possible to remove this member. However, this user also will be removed from the Platform completely if they are not a member of other contracts.

  • It is not possible to remove the last Contract Owner, if there are still members in the Contract.

Editing contracts

A Contract member with the corresponding permissions can edit the Contract in the following ways:

1. Suspend Contract, which means stopping of all of its flows and inability of performing any actions with the Contract, via the following request:

POST /v2/contracts/CONTRACT_ID/suspend/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/suspend \
-X POST \
  -u {EMAIL}:{APIKEY}

2. Unsuspend Contract via the following request:

POST /v2/contracts/CONTRACT_ID/unsuspend/

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID}/unsuspend \
-X POST \
  -u {EMAIL}:{APIKEY}

3. Delete the Contract via the following request:

DELETE /v2/contracts/{CONTRACT_ID} \

Below are request parameters:

URL Parameter Required Description
CONTRACT_ID yes Contract ID

EXAMPLE:

curl -i /v2/contracts/{CONTRACT_ID} \
  -X DELETE \
  -u {EMAIL}:{APIKEY}

IMPORTANT: The actual data deletion will be performed after an API response, as it requires time for termination of all the Contract’s flows containers. A Contract cannot be deleted if any of its Components are being used in a flow in another Contract.

4. Update a Contract’s name and available roles via the following request:

PATCH /v2/contracts/{CONTRACT_ID}

Below are request parameters:

Payload Parameter Required Description
type yes Allowed value: contract
attributes.name yes Contract name
attributes.available_roles[] no Roles available in the Tenant the Contract belongs to.

EXAMPLE:

curl /v2/contracts/{CONTRACT_ID} \
  -X PATCH \
  -u {EMAIL}:{APIKEY} \
  -H 'Content-Type: application/json' -d '
      {
       "data":{
         "type":"contract",
         "id":"{CONTRACT_ID}"
         "attributes":{
            "name":"New Contract Name",
            "available_roles":[
             {
               "scope":"contracts",
               "role":"admin"
             },
             {
               "scope":"workspaces",
               "role":"admin"
             },
             {
               "scope":"workspaces",
               "role":"guest"
             }
           ]
         }
       }
     }'