Identifiers

The iplicit API supports various identifiers with different meanings and purposes.

id

• All records in iplicit have an auto-generated GUID (globally unique) id which is the canonical identifier for that record
• Used to link records together, for example when retrieving a Document via the API the response will include the id of the associated Contact account
• Not visible within the iplicit user interface
• Cannot be specified when creating a record via the api
• Cannot be modified

Code / DocNo

• Most records in iplicit have a Code or, in the case of Documents, a DocNo
• A human readable alternative to the id
• Normally auto-generated by iplicit but some endpoints support setting Code/DocNo via the api
• Visible in the iplicit user interface
• Can be modified but at the risk of broken references
• iplicit will enforce that Code/DocNo is unique within the context of the type being created/updated but not between types
• Many API endpoints support the use of Code as well as id to retrieve, modify and delete existing records

IntRef

• Optional field on many records intended specifically for API use
• Allows integrators to provide an alternative reference that can be used to refer to specific records at a later point
• Not auto-generated by iplicit
• Not visible in the iplicit user interface
• Can be modified but at the risk of broken references
• iplicit will enforce that IntRef is unique within the context of the type being created/updated but not between types
• Some API endpoints support the use of IntRef as well as id and Code to retrieve, modify and delete existing records

Code - IntRef Clash

• When specifying IntRef, care must be taken not to create clashes with Codes
• iplicit enforces uniqueness of Code and IntRef individually, not as a single set
• If one record has an IntRef equal to the Code of another record then it will no longer be possible to use that clashing identifier for API operations and it will be necessary to remove the clash or fallback to using id
• Attempting to use the clashing identifier will result in a HTTP 400 (Bad Request) response

Example

POST /api/contactAccount

{
    "intRef": "CLASH0001",
    "description": "Customer 1",
    "customer": {
        "contactGroupCustomerId": "CU"
    }
}

HTTP 200

"9a762dc4-db6d-4cc8-b59c-9d78f4eb8e72"

GET /api/contactAccount/CLASH0001

HTTP 200

{
  "id": "9a762dc4-db6d-4cc8-b59c-9d78f4eb8e72",
  "code": "123709",
  "intRef": "CLASH0001",
  ....
}

POST /api/contactAccount

{
    "code": "CLASH0001",
    "description": "Customer 2",
    "customer": {
        "contactGroupCustomerId": "CU"
    }
}

HTTP 200

"386d33cb-8393-4035-82c7-3cefaaadcac8"

GET /api/contactAccount/CLASH0001

HTTP 400

{
	"message": " Reference is ambiguous. Please use id or contact support for assistance."
}