IntegrationsReport an integration conflict

Report an integration conflict

Records that a change from an external system was refused by a TimeLog business rule, as an Active conflict.

Lets an integration hand a refusal back to TimeLog instead of retrying forever or dropping it: the conflict is stored as Active with the resolve options TimeLog offers for its type, so a person can decide what to do. Only one kind can be reported at this commit — ErrorCode 37886 (a task in a completed task-driven revenue contract cannot be deleted), offering "close and copy" or "delete and copy" the task. Any other code is refused with 37985.

Use it to:

  • Your ERP deleted a task that TimeLog refuses to delete (37886): report it here instead of retrying the delete.

Not for:

  • Logging arbitrary sync errors — only error codes with a registered conflict type are accepted.

Behaviour:

  • Not idempotent.
  • Not safe to retry blindly. Every call inserts a new conflict; there is no deduplication on ErrorCode / ExternalSystemID / message. List Active conflicts before retrying.
  • Duplicates: None.
  • Changes are visible to the next read immediately.

Call first: GET /v1/external-systems

Next: GET /v1/integration-conflicts/{integrationConflictID}

See also: GET /v1/integration-conflicts

Not yet documented: behaviour → events emitted; examples (success).

curl -X POST "https://app3.timelog.com/your-account/api/v1/integration-conflicts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "ErrorCode": 42,
  "ErrorMessage": "example_string",
  "ExternalSystemID": 123
}'
{
  "Properties": {
    "ConflictID": 123,
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "ConflictDateTime": "2024-12-25T10:00:00Z",
    "ConflictType": 42,
    "ConflictStatusType": 42,
    "ResolveOptionTypes": [
      "null"
    ],
    "ResolveOptionTypeUsed": 42,
    "ResolvedByUserID": "null",
    "OriginalErrorCode": 42,
    "OriginalErrorMessage": "example_string",
    "ExternalSystemID": 123
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}
POST
/v1/integration-conflicts
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.
Content-Typestring
Required

The media type of the request body

Options: application/json
ErrorCodeinteger
Required

The TimeLog error code the external change ran into. Must be a code that has a conflict type: at this commit only 37886 ("Task in completed task driven revenue contract cannot be deleted"), which yields ConflictType 2. Stored as OriginalErrorCode. Can be set on create only. - 0, negative or missing — 400 "'Error Code' must not be empty." / "must be greater than '0'." - any code other than 37886 — 500 Code 102, ErrorCode 37985 (no conflict type for that code).

ErrorMessagestring
Required

The error message to show for the conflict. Stored unchanged as OriginalErrorMessage; TimeLog does not check that it matches ErrorCode. Can be set on create only. - null, empty or whitespace-only — 400 "'Error Message' must not be empty."

Min length: 1
ExternalSystemIDinteger
Required

The external system the conflicting change came from. Can be set on create only. Refers to ExternalSystemRead.ID. Look up valid values with GET /v1/external-systems. - 0, negative or missing — 400 "'External System ID' must not be empty." / "must be greater than '0'." - not an existing external system — 500 Code 102, ErrorCode 37045. Valid values come from GET /v1/external-systems.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).

The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.

Not yet documented: how to obtain a token.

Not yet documented: token lifetime.

Body

application/json
ErrorCodeinteger
Required

The TimeLog error code the external change ran into. Must be a code that has a conflict type: at this commit only 37886 ("Task in completed task driven revenue contract cannot be deleted"), which yields ConflictType 2. Stored as OriginalErrorCode.

Can be set on create only.

  • 0, negative or missing — 400 "'Error Code' must not be empty." / "must be greater than '0'."

  • any code other than 37886 — 500 Code 102, ErrorCode 37985 (no conflict type for that code).

ErrorMessagestring
Required

The error message to show for the conflict. Stored unchanged as OriginalErrorMessage; TimeLog does not check that it matches ErrorCode.

Can be set on create only.

  • null, empty or whitespace-only — 400 "'Error Message' must not be empty."
ExternalSystemIDinteger
Required

The external system the conflicting change came from.

Can be set on create only.

Refers to ExternalSystemRead.ID. Look up valid values with GET /v1/external-systems.

  • 0, negative or missing — 400 "'External System ID' must not be empty." / "must be greater than '0'."

  • not an existing external system — 500 Code 102, ErrorCode 37045.

Valid values come from GET /v1/external-systems.

Responses

Propertiesobject

A record that a change coming from an external system could not be applied in TimeLog because of a TimeLog business rule, kept so that someone can decide how to resolve it. At this commit exactly one kind is supported: a task that cannot be deleted because it sits in a completed task-driven revenue contract (TimeLog error 37886). Conflicts are created Active and carry the resolve options TimeLog offers for their type; REST v1 has no operation to change their status.

Linksarray
Actionsobject[]