Endpoints

Last updated 7 months ago

Was this helpful?

Find template by entity type

get

Using the Atlas CRM API it is possible to use endpoints that can create, alter and remove entities. To properly use these endpoints it is necessary to know about the template an entity is based on.

For example, one must know the field_id of the name field to create a sale entity.

The following endpoint can provide this information and make using the Atlas CRM API a lot easier. A possible use case is to create a form that can create and/or alter entities based on the template information that this endpoint provides.

Authorizations

Path parameters

entity-typestring · enumRequiredPossible values:

Responses

200Success

application/json

get

GET /api/1.0/workspace/CRM/template/{entity-type} HTTP/1.1
Host: 
Accept: */*

200Success

{
  "sections": [
    {
      "name": "text",
      "fields": [
        {
          "id": "text",
          "label": "text",
          "type": "text",
          "default-value": "text",
          "allowed-values": {},
          "config": {
            "currency": "text",
            "max": 1,
            "min": 1
          },
          "required": true
        }
      ]
    }
  ]
}

Retrieve paginated entities

get

Use this endpoint to retrieve multiple entities at once, with the possibility to filter the results.

Sorting

Entities are sorted by their name-field by default. You can alter this behaviour by supplying another field-id with the sort-by query parameter.

Pagination

The default size of the result is 20, but can be changed to a maximum of 100.

You will find the next url in the _links property when there is a next page available.

Filtering

You can filter the results based on the fields of an entity. There are different operators for the different field types.

Operator	Description
eq	Equals - Exact match with supplied filter.
contains	Contains - Partial match with supplied filter.
gte	Greater than / Equals - Value is equal or greater than the supplied filter.
lte	Less than / Equals - Value is equal or less than the supplied filter.

Field type	Operators	Default operator	Value format
string (Single line text)	eq, contains	eq	any string
text (Multi line text)	contains	contains	any string
date	eq, gte, lte	eq	string - yyyy-mm-dd
timestamp	eq, gte, lte	eq	string - ISO 8601 Datetime
decimal	eq, gte, lte	eq	any number
user	eq	eq	string - Atlassian account-id
single-select	eq	eq	string - label of an option
multi-select	contains	contains	string - label of an option

You can add a filter as a query parameter.

?fields.FIELD_ID[OPERATOR]=VALUE

For example:

?fields.contact-email[contains]=gmail.com

If no operator is supplied, the default operator will be used:

?fields.contact-name=Tom
?fields.contact-name[eq]=Tom

These query parameters will have the same result, as 'eq'
is the default operator for the field 'contact-name'

Multiple filters

You can add as many filters as you wish by just adding more query parameters. In the example below you will find all open sales with a revenue of 500 or more.

?fields.sale-balance[gte]=500&fields.sale-status=open

Adding the same field-id/operator combination will result in an OR operator. This can be used for example when you want to retrieve all closed sales (sales with status 'lost' OR 'won').

?fields.sale-status=won&fields.sale-status=lost

Authorizations

Query parameters

typestring · enumRequiredPossible values:

sizeinteger · int64Optional

sort-typestring · enumOptionalPossible values:

sort-bystringOptional

cursorstringOptional

Responses

200Success

application/json

get

GET /api/1.0/workspace/CRM/entities?type=company HTTP/1.1
Host: 
Accept: */*

200Success

{
  "items": [
    {
      "id": "text",
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "type": "company",
      "_links": {
        "self": {
          "href": "text"
        },
        "app": {
          "href": "text"
        }
      }
    }
  ],
  "total": 1,
  "_links": {
    "self": {
      "href": "text"
    },
    "next": {
      "href": "text"
    }
  }
}

Retrieve entity by id

get

Authorizations

Path parameters

entity-idstringRequired

Responses

200Success

application/json

404Error

application/json

get

GET /api/1.0/workspace/CRM/entities/{entity-id} HTTP/1.1
Host: 
Accept: */*

{
  "id": "text",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "type": "company",
  "_links": {
    "self": {
      "href": "text"
    },
    "app": {
      "href": "text"
    }
  }
}

Delete entity by id

delete

Authorizations

Path parameters

entity-idstringRequired

Responses

200Success

application/json

404Error

application/json

405Error

application/json

delete

DELETE /api/1.0/workspace/CRM/entities/{entity-id} HTTP/1.1
Host: 
Accept: */*

{
  "id": "text",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "type": "company",
  "_links": {
    "self": {
      "href": "text"
    },
    "app": {
      "href": "text"
    }
  }
}

Get paginated linked entities

get

See Retrieve paginated entities for more information about filtering, sorting and pagination.

Authorizations

Path parameters

entity-idstringRequired

Query parameters

typestring · enumRequiredPossible values:

sizeinteger · int64Optional

sort-typestring · enumOptionalPossible values:

sort-bystringOptional

cursorstringOptional

Responses

200Success

application/json

400Error

application/json

404Error

application/json

get

GET /api/1.0/workspace/CRM/entities/{entity-id}/links?type=company HTTP/1.1
Host: 
Accept: */*

{
  "items": [
    {
      "roles": [
        "text"
      ],
      "entity": {
        "id": "text",
        "fields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "type": "company",
        "_links": {
          "self": {
            "href": "text"
          },
          "app": {
            "href": "text"
          }
        }
      },
      "_links": {
        "self": {
          "href": "text"
        }
      }
    }
  ],
  "total": 1,
  "_links": {
    "self": {
      "href": "text"
    },
    "next": {
      "href": "text"
    }
  }
}

Retrieve link information

get

Authorizations

Path parameters

entity-idstringRequired

other-entity-idstringRequired

Responses

200Success

application/json

400Error

application/json

404Error

application/json

get

GET /api/1.0/workspace/CRM/entities/{entity-id}/links/{other-entity-id} HTTP/1.1
Host: 
Accept: */*

{
  "roles": [
    "text"
  ],
  "entity": {
    "id": "text",
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "type": "company",
    "_links": {
      "self": {
        "href": "text"
      },
      "app": {
        "href": "text"
      }
    }
  },
  "_links": {
    "self": {
      "href": "text"
    }
  }
}

Delete entity link

delete

Authorizations

Path parameters

entity-idstringRequired

other-entity-idstringRequired

Responses

200Success

application/json

400Error

application/json

404Error

application/json

delete

DELETE /api/1.0/workspace/CRM/entities/{entity-id}/links/{other-entity-id} HTTP/1.1
Host: 
Accept: */*

{
  "roles": [
    "text"
  ],
  "entity": {
    "id": "text",
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "type": "company",
    "_links": {
      "self": {
        "href": "text"
      },
      "app": {
        "href": "text"
      }
    }
  },
  "_links": {
    "self": {
      "href": "text"
    }
  }
}

Create new entity

post

Use this endpoint to create a new company, contact or sale.

Template

You will have to use the Atlas CRM Template to create a new entity. See the Templates Endpoint to retrieve template information.

Each field type in the template has a different value format.

Field type	Value format
string (Single line text)	any string
text (Multi line text)	any string
date	string - yyyy-mm-dd
timestamp	string - ISO 8601 Datetime
decimal	any number
user	string - Atlassian account-id
single-select	string - label of an option
multi-select	array - labels of options

Fields in payload

The fields payload should be a mapping of field-id and value.

{ "type": "contact",
  "fields": {"contact-name": "Eric",
             "contact-email": "Eric@somethingrandom.random",
             "97e9b775-8524-4aaf-ba48-9dc4d7123473": "My custom data"}}

Authorizations

Body

typestring · enumRequiredPossible values:

Responses

201Success

application/json

400Error

application/json

post

POST /api/1.0/workspace/CRM/entities HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "type": "company",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "text",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "type": "company",
  "_links": {
    "self": {
      "href": "text"
    },
    "app": {
      "href": "text"
    }
  }
}

Update entity by id

put

Use this endpoint to update a company, contact or sale.

Template

You will have to use the Atlas CRM Template to update an entity. See the Templates Endpoint to retrieve template information.

Each field type in the template has a different value format.

Field type	Value format
string (Single line text)	any string
text (Multi line text)	any string
date	string - yyyy-mm-dd
timestamp	string - ISO 8601 Datetime
decimal	any number
user	string - Atlassian account-id
single-select	string - label of an option

Fields in payload

The fields payload should be a mapping of field-id and value. You only have to supply the fields that you which to update. To remove a value, simply pass is through as null.

{"fields": {"contact-name": "Erica", 
            "contact-email": null}}

Authorizations

Path parameters

entity-idstringRequired

Body

Responses

200Success

application/json

404Error

application/json

put

PUT /api/1.0/workspace/CRM/entities/{entity-id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "text",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "type": "company",
  "_links": {
    "self": {
      "href": "text"
    },
    "app": {
      "href": "text"
    }
  }
}

Create a new link

post

Authorizations

Path parameters

entity-idstringRequired

Body

entity-idstringRequired

rolesstring[]Optional

Responses

201Success

application/json

400Error

application/json

404Error

application/json

post

POST /api/1.0/workspace/CRM/entities/{entity-id}/links HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "entity-id": "text",
  "roles": [
    "text"
  ]
}

{
  "roles": [
    "text"
  ],
  "entity": {
    "id": "text",
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "type": "company",
    "_links": {
      "self": {
        "href": "text"
      },
      "app": {
        "href": "text"
      }
    }
  },
  "_links": {
    "self": {
      "href": "text"
    }
  }
}

Update link data

put

Authorizations

Path parameters

entity-idstringRequired

other-entity-idstringRequired

Body

rolesstring[]Required

Responses

200Success

application/json

400Error

application/json

404Error

application/json

put

PUT /api/1.0/workspace/CRM/entities/{entity-id}/links/{other-entity-id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "roles": [
    "text"
  ]
}

{
  "roles": [
    "text"
  ],
  "entity": {
    "id": "text",
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "type": "company",
    "_links": {
      "self": {
        "href": "text"
      },
      "app": {
        "href": "text"
      }
    }
  },
  "_links": {
    "self": {
      "href": "text"
    }
  }
}

Link entity to issues

post

Authorizations

Path parameters

entity-idstringRequired

Body

issue-idsstring[]Required

Responses

200Success

application/json

400Error

application/json

404Error

application/json

405Error

application/json

post

POST /api/1.0/workspace/CRM/entities/{entity-id}/issues HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "issue-ids": [
    "text"
  ]
}

{
  "issue-ids": [
    "text"
  ]
}

Unlink entity from issues

delete

Authorizations

Path parameters

entity-idstringRequired

Body

issue-idsstring[]Required

Responses

200Success

application/json

400Error

application/json

404Error

application/json

405Error

application/json

delete

DELETE /api/1.0/workspace/CRM/entities/{entity-id}/issues HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "issue-ids": [
    "text"
  ]
}

{
  "issue-ids": [
    "text"
  ]
}

Create new comment

post

Formats

The format field can only be "plain-text" at this moment. This field is mandatory to prevent breaking changes when more formats will be supported.

Account ID

Supply the Atlassian Account ID of the author of the comment in the account-id field.

You can find account-ids by using the Jira or Confluence REST API. This is an example of how to find your own Atlassian Account ID:

GET https://YOURBASEURL.atlassian.net/rest/api/latest/myself

Example request

{ "format": "plain-text",
  "account-id": "0e3b584c-random-8a57-367dd049c3a4",
  "comment": "Created this comment from the API \n Kind regards"}

Authorizations

Path parameters

entity-idstringRequired

Body

formatstring · enumRequiredPossible values:

commentstringRequired

account-idstringRequired

Responses

201Success

application/json

400Error

application/json

post

POST /api/1.0/workspace/CRM/entities/{entity-id}/comments HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "format": "plain-text",
  "comment": "text",
  "account-id": "text"
}

{
  "id": "text",
  "comment": "text",
  "account-id": "text"
}

Endpoints

Endpoints

Templates

Entities

Linking

Jira issues

Comments

Templates

Entities

Linking

Jira issues

Comments

Find template by entity type

Retrieve paginated entities

Sorting

Pagination

Filtering

Multiple filters

Retrieve entity by id

Delete entity by id

Get paginated linked entities

Retrieve link information

Delete entity link

Create new entity

Template

Fields in payload

Update entity by id

Template

Fields in payload

Create a new link

Update link data

Link entity to issues

Unlink entity from issues

Create new comment

Formats

Account ID

Example request