Skip to content

Read a record – GET /api/v1/records/{entityId}/{recordId}

Reads one record with all its fields and, on request, the records related to it through one or more relationships. This page is the reference for the operation.

1. At a glance
Purpose Read one record by its ID
Method and path GET /api/v1/records/{entityId}/{recordId}
Typical use Fetch a customer with its contacts; check a record after an update
Permissions Valid token. The record must lie within the "Read Limits" of the API user.
Success 200 OK, the record in the body
Related Query records to find records by their values, Fields and values

2. Request

Path parameters

Parameter Meaning Required
entityId ID of the entity Yes
recordId ID of the record (its "RecId") Yes

Query parameters

Parameter Meaning Default
relationshipId ID of a relationship of the entity. The related records are returned in relationships. Can be given several times. none – no related records

The relationship ID is copied with "Copy ID" in the management view of the relationships. Only relationships that belong to the entity of the record can be used.

3. Response

200 OK with the record in the form described in Fields and values. Without relationshipId, relationships is null. With it, there is one entry per requested relationship:

{
  "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13",
  "entityName": "Customer",
  "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58",
  "fields": [
    { "fieldDefId": "0d5c8e3a-7b21-4f9e-a6d0-3c4b5e6f7a81", "field": "CustomerNumber", "storageName": "CustNo", "type": "String", "value": "K-1001" },
    { "fieldDefId": "5d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f9a", "field": "Name", "storageName": "Name", "type": "String", "value": "ACME Ltd." }
  ],
  "relationships": [
    {
      "relationshipDefId": "c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "relationshipName": "CustomerContacts",
      "childEntityDefId": "4e8a1c3f-5b7d-4e9f-a1c3-5e7a9c1e3f5b",
      "childEntityName": "Contact",
      "records": [
        {
          "entityDefId": "4e8a1c3f-5b7d-4e9f-a1c3-5e7a9c1e3f5b",
          "entityName": "Contact",
          "entityRecId": "d7e8f9a0-b1c2-4d3e-8f4a-5b6c7d8e9f0a",
          "fields": [
            { "fieldDefId": "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c", "field": "LastName", "storageName": "LastName", "type": "String", "value": "Miller" },
            { "fieldDefId": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d", "field": "Email", "storageName": "Email", "type": "String", "value": "j.miller@acme.example" }
          ],
          "relationships": null
        }
      ]
    }
  ]
}
Property Meaning
relationships[].relationshipDefId, relationshipName ID and technical name of the relationship
relationships[].childEntityDefId, childEntityName The entity of the related records
relationships[].records The related records, each with all its fields. Their own related records are not included.

(The example shows only some of the fields.)

4. Behaviour

  • The record is read with the "Read Limits" of the API user. A record outside them is answered with 404 record_not_found, so the caller cannot tell it from a record that does not exist.
  • The record is opened as in a form; rules that run when a record is opened run, and their results are part of the response. Nothing is saved.
  • Related records are read as for a form showing the record, so the read limits apply to them as well (see Roles and permissions).
  • Related records are returned completely – there is no paging. For many related records, use a query with a related clause or a field that links to the record.

5. Status and error codes

HTTP status error Cause
200 – The record was read
400 relationship_not_found A relationshipId does not belong to the entity
401 – No valid token
404 entity_not_found No entity with this ID
404 record_not_found No record with this ID, or not within the read limits
404 – (empty body) An ID in the path is not a valid ID
500 server_error, query_failed Unexpected error, see Errors

6. Examples

Only the record:

curl https://nexxcite.example.com/api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13/9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58 \
  -H "Authorization: Bearer $TOKEN"

With contacts and invoices (two relationships):

curl "https://nexxcite.example.com/api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13/9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58?relationshipId=c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f&relationshipId=d3e5f7a9-2b4c-4d6e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer $TOKEN"

7. Limitations

  • Related records are returned one level deep and without paging.
  • Files and images of the record are not part of the response.
  • A record can only be read by its ID. To find it by other values, use a query.