Managing Contracts

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

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 https://api.elastic.io/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 https://api.elastic.io/v2/contracts/{CONTRACT_ID}?include=members,invites \
   -u {EMAIL}:{APIKEY}

2. Get Contracts via the following request:

GET https://api.elastic.io/v2/contracts/

EXAMPLE:

curl https://api.elastic.io/v2/contracts/
  -u {EMAIL}:{APIKEY}

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

GET https://api.elastic.io/v2/contracts/CONTRACT_ID/members/

Below are request parameters:

URL Parameter	Required	Description
`CONTRACT_ID`	yes	Contract ID

EXAMPLE:

curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/ \
  -u {EMAIL}:{APIKEY}

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

GET https://api.elastic.io/v2/contracts/CONTRACT_ID/invites/

Below are request parameters:

URL Parameter	Required	Description
`CONTRACT_ID`	yes	Contract ID

EXAMPLE:

curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/ \
   -u {EMAIL}:{APIKEY}

4. Get Contract roles via the following request:

GET https://api.elastic.io/v2/contracts/CONTRACT_ID/roles/

Below are request parameters:

URL Parameter	Required	Description
`CONTRACT_ID`	yes	Contract ID

EXAMPLE:

curl https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/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 https://api.elastic.io/v2/contracts/CONTRACT_ID/suspend/

Below are request parameters:

URL Parameter	Required	Description
`CONTRACT_ID`	yes	Contract ID

EXAMPLE:

curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/suspend \
-X POST \
  -u {EMAIL}:{APIKEY}

2. Unsuspend Contract via the following request:

POST https://api.elastic.io/v2/contracts/CONTRACT_ID/unsuspend/

Below are request parameters:

URL Parameter	Required	Description
`CONTRACT_ID`	yes	Contract ID

EXAMPLE:

curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/unsuspend \
-X POST \
  -u {EMAIL}:{APIKEY}

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

PATCH https://api.elastic.io/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 https://api.elastic.io/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"
             }
           ]
         }
       }
     }'

Managing Contracts

Getting Contract Data

Editing Contract Memberships

Editing contracts

Related links