Read one module’s fields again

POST

/orgs/{org}/discovery/modules/{module}/read

curl --request POST \
  --url 'https://api.sloose.com/orgs/org_9f3c/discovery/modules/example/read?connector=con_8f2a' \
  --header 'Authorization: Bearer <token>'

• Production
• Staging

Reads the fields of ONE module of the connection ?connector= names, through its stored grant, and brings what is held in line with them by the comparison a whole discovery makes: a picklist that gained an option, a relabelled field, a new field. One call to the CRM. changed is true only when something differed, and only then does the configuration’s registryVersion move, so a module that has not changed moves nothing.

For a person who sees a value their file holds called unmapped because the CRM gained an option after the last discovery: any member may ask, since it reads one module and writes only what the CRM now says. A module read less than 30 seconds ago is answered read: false rather than asked of the CRM again, and one that another read holds right now is answered read: false, busy: true: that read’s answer has not landed yet, so read the configuration again after a moment. {module} is the module’s api name, as the connection holds it.

Authorizations

• sessionAuth
• apiTokenAuth

Parameters

Path Parameters

org

required

The org id the session was issued for. A token for one org can never read another.

string

Example

org_9f3c

The org id the session was issued for. A token for one org can never read another.

module

required

string

>= 1 characters <= 200 characters

Query Parameters

connector

The connection this is about, by id: one of the org’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another org’s, or another person’s — is 404 CONNECTION_NOT_FOUND.

string

Example

con_8f2a

The connection this is about, by id: one of the org’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another org’s, or another person’s — is 404 CONNECTION_NOT_FOUND.

Responses

200

What the read did.

Media typeapplication/json

object

module

required

string

read

required

False when the CRM was not asked: the module was read a moment ago, or the read failed (error says why).

boolean

changed

required

boolean

busy

True when the CRM was not asked because another read of this module is under way right now (#1163): its answer lands when it finishes, so read the configuration again after a moment. Absent otherwise.

boolean

busyForMs

With busy: how long, in milliseconds, until that other read’s lease ends — the most it can take to land or be given up. Read the configuration again by then. A duration, so the caller’s clock does not matter.

integer

readAt

required

string | null

error

string

Example^generated

{
  "module": "example",
  "read": true,
  "changed": true,
  "busy": true,
  "busyForMs": 1,
  "readAt": "example",
  "error": "example"
}

400

The request named no connection (code: CONNECTION_REQUIRED, with connections: the ones this bearer may name). Nothing picks one for a request that does not say (design §14.8).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

No bearer, or one that is expired, revoked or no longer resolves to a member.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

The bearer’s role is too low, or it was issued for a different org.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

404

?connector= names a connection this person may not use (CONNECTION_NOT_FOUND), or the connection holds no such module, or the CRM no longer reports it (MODULE_NOT_FOUND).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

409

The connection holds no working grant — disconnected, or Zoho stopped honouring it — so there is nothing to read with.

Media typeapplication/json

object

error

required

string

code

required

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}