Skalin documentation

Opportunities

Opportunities Management API

This API allows the administration of opportunities: the expansion, upsell and renewal deals opened on a customer account.

Any undocumented property or method may be changed or removed without notice.

Info

Opportunities list endpoint is always paginated. Refer to pagination section for more details.

# Singular path

Note: the resource is exposed in the singular, /opportunity, not /opportunities. Pipelines, on the other hand, are plural: /opportunity-pipelines.

# Pipelines and stages

An opportunity moves through the stages of a pipeline. A workspace can define several of them, for example one for renewals and one for upsells.

Each stage carries its own win probability, copied onto the opportunities sitting in it through the probability and stageLabel fields. Both are read only: they follow the stage and cannot be written directly.

A pipeline must at least offer the open, won and lost stages.

# Automatic closing

won and lost are the terminal stages. Moving an opportunity into one of them stamps endAt with the current date; moving it back to any other stage clears endAt.

The endAt field is managed by Skalin and ignored if sent in the request body.

# Identifying the account

On creation, the account can be designated in two ways:

  • with customerId, the Skalin id of the account;
  • with customer, a term matched — case insensitively — against the account's domain, refId or name.

If customer matches no account, the call returns a 400.

# userId and teamId

Two keywords save you from resolving an id:

  • in userId, OWNER assigns the opportunity to the owner of the customer account;
  • in teamId, CUSTOMER_TEAM assigns the opportunity to the whole team of the customer account.

# users

As for tasks, the users field accepts designations rather than plain ids:

[{ "value": "id", "type": "USER" }]
1
[{ "value": "field id", "type": "CUSTOM" }]
1

Note: Only customizable fields of type USER can be used.

[{ "value": "OWNER", "type": "SYSTEM" }]
1

On read, the API simply returns the list of the users' ids.

# swagger

Contributors: Julien