Read up to a hundred records by id
const url = 'https://api.sloose.com/orgs/org_9f3c/connectors/cnn_9f2a/records/Accounts/by-ids?ids=1000000000000000001%2C1000000000000000002&run=0199c1f2-7a3e-7b1c-9d2e-4f5a6b7c8d9e&fields=Account_Name%2CAccount_Ref&check=Account_Ref';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.sloose.com/orgs/org_9f3c/connectors/cnn_9f2a/records/Accounts/by-ids?ids=1000000000000000001%2C1000000000000000002&run=0199c1f2-7a3e-7b1c-9d2e-4f5a6b7c8d9e&fields=Account_Name%2CAccount_Ref&check=Account_Ref' \ --header 'Authorization: Bearer <token>'Reads 1 to 100 records of a module by id — for Zoho, one call for every 50 fields it asks for (it refuses a read naming more, #1925): the fields named in fields that the module has, so naming up to 50 is one call however many fields the module has, or with none named every field the connection’s discovery read for the module. Each call is one API credit and is made for every id, where a record a call spends one each (P0, #1741). The answer is one entry per id, in the order asked: the record, or null where the destination does not have it. A record carries every field the connection’s discovery read for the module (the CRM refuses a read by id that names none) — or, where the caller names fields, only those the module has, and the id — and its $display_name where the module’s naming field is known (for a read that names fields, only where that is already kept and among them). An id asked twice is answered twice from one read. Only a module of the connection (MODULE_NOT_FOUND).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The organisation id the session was issued for. A token for one organisation can never read another.
Example
org_9f3cThe organisation id the session was issued for. A token for one organisation can never read another.
The connector id, from GET /orgs/{org}/connectors.
Example
cnn_9f2aThe connector id, from GET /orgs/{org}/connectors.
The module’s API name in the destination.
Example
AccountsThe module’s API name in the destination.
Query Parameters
Section titled “Query Parameters”The record ids, comma separated, 1 to 100.
Example
1000000000000000001,1000000000000000002The record ids, comma separated, 1 to 100.
The run this read is made under, where it is made by one: the id from POST /entitlements/runs/authorise. It changes nothing about the read and is refused for nothing. It is used only when the read is refused because the CRM’s API allowance for the day is spent (429): an open run of this organisation on this connection is then marked as stopped by that (stoppedBy: "allowance" on the run), so that it is told from a run a person stopped. A name that is no such run marks nothing.
Example
0199c1f2-7a3e-7b1c-9d2e-4f5a6b7c8d9eThe run this read is made under, where it is made by one: the id from POST /entitlements/runs/authorise. It changes nothing about the read and is refused for nothing. It is used only when the read is refused because the CRM’s API allowance for the day is spent (429): an open run of this organisation on this connection is then marked as stopped by that (stoppedBy: "allowance" on the run), so that it is told from a run a person stopped. A name that is no such run marks nothing.
The fields the caller will read, comma separated: the records carry these, and the id. Names the module does not have (as its discovery read it) are left out, and said in the answer’s dropped. Absent, every field the module has — which for Zoho is one call for every 50 fields, and one call when the caller names no more than 50.
Example
Account_Name,Account_RefThe fields the caller will read, comma separated: the records carry these, and the id. Names the module does not have (as its discovery read it) are left out, and said in the answer’s dropped. Absent, every field the module has — which for Zoho is one call for every 50 fields, and one call when the caller names no more than 50.
Where no fields are named (a read of every field), names to check all the same, comma separated: those the module does not have are said in dropped, and nothing else changes. Ignored beside fields, which are checked themselves.
Example
Account_RefWhere no fields are named (a read of every field), names to check all the same, comma separated: those the module does not have are said in dropped, and nothing else changes. Ignored beside fields, which are checked themselves.
Responses
Section titled “Responses”One entry per id, in the order asked: the record, or null.
object
object
Added by Sloose, not the CRM: the record’s name as the CRM shows it, read from the field its module names records by (Zoho’s display_field — Account_Name, Full_Name, Vendor_Name). Absent when that field is empty, and from a search or a single record when the field could not be learned just then.
The names the module does not have as the connection’s discovery read it, in the order named (#2119): those in fields, or, for a read of every field, those in check. No record carries them, so a caller that reads one gets nothing for it, and should say so rather than read on. Empty where every name was a field, and where none was named or checked.
Examplegenerated
{ "records": [ { "$display_name": "example" } ], "dropped": [ "example" ]}No ids, or more than 100 (BATCH_SIZE).
object
Examplegenerated
{ "error": "example"}No bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The bearer’s role is too low (code: ROLE_REQUIRED), or it was issued for a different organisation; the organisation has been closed (code: ORG_CLOSED, either kind of bearer); the person is banned (code: BANNED, a session); or it is a session that is signed in but in no organisation (code: NO_ORG): one that never joined one, or whose person was taken out of the one it was in, or left it. Signing in again changes nothing for NO_ORG; choosing or making an organisation does.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}No such connector, or it is not visible to this session (NOT_FOUND); or the connection has no module of that name — only its modules, as its discovery read them, are asked of the CRM (MODULE_NOT_FOUND).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}Zoho rejected the request.
object
object
True when Zoho gave no answer that says what was done — the connection dropped or timed out, Zoho failed on its side (a 5xx, or the same for the one record inside a 2xx), the answer was lost after its status or was not JSON, or Zoho said it made the record without saying which — so what was asked may have been done all the same: a create sent again after one may make a second record. A write that went unanswered stays counted, and its row may be written again for nothing. False when Zoho answered by declining (a 4xx, or a per-record refusal inside a 2xx), which made nothing.
True when Zoho asked for fewer calls and declined this one (TOO_MANY_REQUESTS): nothing was done, and the same call a little later may land — a write included, since a declined one made nothing. Absent from an older API.
How long Zoho asked to be left alone before the next call, in milliseconds, from its Retry-After; also sent as this response’s own Retry-After, in seconds. Null when it said nothing.
True when the rate limit is the CRM’s daily allowance of API calls used up — a 429 whose X-API-CREDITS-REMAINING says none are left — which waiting seconds does not bring back. Without that header the two limits cannot be told apart, and this is false.
Examplegenerated
{ "error": "example", "zoho": { "code": "example", "status": 1, "details": "example", "retryable": true, "response": "example", "unanswered": true, "rateLimited": true, "retryAfterMs": 1, "quotaSpent": true }}Zoho is throttling how often this connection’s access is renewed — ten tokens from one grant in ten minutes — so nothing was sent (code: CONNECTION_THROTTLED; written: false on a write). Retry-After says when to ask again. The connection is kept: only a grant Zoho refuses ends it. A renewal throttled after the call reached Zoho is Zoho’s rate limit, relayed as a 502 with zoho.rateLimited.
Or the CRM’s API allowance for the last 24 hours is spent (zoho.quotaSpent: true, zoho.rateLimited: true, zoho.retryable: false), said one of two ways. Zoho itself refused the call (zoho.code: TOO_MANY_REQUESTS, credits left 0): relayed as this 429, never a 502, since asking again soon is refused again. Or the tenant’s gate refused it before it was sent, because Zoho had already said so: this API’s own refusal, with no zoho (code: DAILY_ALLOWANCE_SPENT; written: false on a write). Neither carries Retry-After: Zoho’s day is a rolling 24 hours and it names no time at which credits return, so Sloose lets one call a minute through to ask, and the first one answered is the allowance’s return. GET …/credits says whether the day is held spent (spent, spentAt). A system that does name its renewal is answered with Retry-After until then.
object
Why: CONNECTION_UNAVAILABLE (502) when a Zoho token for the connection will not refresh, CONNECTION_THROTTLED (429) when Zoho is throttling its renewal — ten tokens from one grant in ten minutes — and the connection is kept, and DAILY_ALLOWANCE_SPENT (429) when the connected system said a daily allowance the call draws on is spent, which waiting seconds does not bring back.
On a write: refused before the record was sent to the CRM, so nothing was written and a retry makes no second record. Absent from a read.
Example
{ "written": false}Zoho is rate-limiting (zoho.unanswered false: nothing was done), or did not answer — it could not be reached, failed on its side, or answered without saying what it did (zoho.unanswered true: what was asked may have been done). Or this API could not use the connection before anything was sent — a Zoho token that will not refresh (code: CONNECTION_UNAVAILABLE) — and says so on a write with written: false: nothing was written.
object
object
True when Zoho gave no answer that says what was done — the connection dropped or timed out, Zoho failed on its side (a 5xx, or the same for the one record inside a 2xx), the answer was lost after its status or was not JSON, or Zoho said it made the record without saying which — so what was asked may have been done all the same: a create sent again after one may make a second record. A write that went unanswered stays counted, and its row may be written again for nothing. False when Zoho answered by declining (a 4xx, or a per-record refusal inside a 2xx), which made nothing.
True when Zoho asked for fewer calls and declined this one (TOO_MANY_REQUESTS): nothing was done, and the same call a little later may land — a write included, since a declined one made nothing. Absent from an older API.
How long Zoho asked to be left alone before the next call, in milliseconds, from its Retry-After; also sent as this response’s own Retry-After, in seconds. Null when it said nothing.
True when the rate limit is the CRM’s daily allowance of API calls used up — a 429 whose X-API-CREDITS-REMAINING says none are left — which waiting seconds does not bring back. Without that header the two limits cannot be told apart, and this is false.
object
Why: CONNECTION_UNAVAILABLE (502) when a Zoho token for the connection will not refresh, CONNECTION_THROTTLED (429) when Zoho is throttling its renewal — ten tokens from one grant in ten minutes — and the connection is kept, and DAILY_ALLOWANCE_SPENT (429) when the connected system said a daily allowance the call draws on is spent, which waiting seconds does not bring back.
On a write: refused before the record was sent to the CRM, so nothing was written and a retry makes no second record. Absent from a read.
Example
{ "written": false}The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.
object
Example
{ "code": "MAINTENANCE"}Headers
Section titled “Headers”Seconds until asking again is worth it (300 while the switch is on).