ProjectsSet an external key on a task

Set an external key on a task

Creates or replaces the key a task has in one external system.

Upsert keyed on (task, external system): if the task already has a key for that system it is overwritten. TimeLog does not enforce uniqueness of the key value: the same ExternalID can be stored on several tasks of the same system, and DELETE then removes it from all of them.

Use it to:

  • Store the ID of the source record after syncing a task from an ERP / CRM

Behaviour:

  • Idempotent.
  • Safe to retry.
  • Duplicates: The same ExternalID can be stored on several tasks of one external system without error (no unique constraint on the value).
  • Changes are visible to the next read immediately.

Next: GET /v1/task/{taskID}/external-keys

See also: PUT /v1/time-registration/{timeRegistrationID}/external-keys

Not yet documented: examples; related → prerequisites.

curl -X PUT "https://app3.timelog.com/your-account/api/v1/task/123/external-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "ExternalID": "example_string",
  "ExternalSystemID": 123,
  "ExternalSystemName": "John Doe",
  "DomainType": 42,
  "DomainID": 123,
  "DomainGuid": "123e4567-e89b-12d3-a456-426614174000",
  "IsIgnored": true
}'
{
  "Properties": {
    "ExternalID": "example_string",
    "ExternalSystemID": 123,
    "ExternalSystemName": "John Doe",
    "DomainType": 42,
    "DomainID": 123,
    "DomainGuid": "123e4567-e89b-12d3-a456-426614174000",
    "IsIgnored": true
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}
PUT
/v1/task/{taskID}/external-keys
PUT
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.
path
taskIDinteger
Required

Route constraint :int.

Content-Typestring
Required

The media type of the request body

Options: application/json
ExternalIDstring

The object's identifier in the external system. Key from your own system. Uniqueness is not enforced. NOT unique: two time registrations (or two projects, or two tasks) can carry the same ExternalID in the same external system. TimeLog does not deduplicate by external key — integrators must. Values over 250 characters are not rejected by validation (server outcome unknown).

Max length: 250
ExternalSystemIDinteger

The external system the key belongs to. Refers to ExternalSystemRead.ExternalSystemID. Look up valid values with GET /v1/external-systems. Unknown ID fails with business rule 37045.

DomainTypeinteger

The object type: 147 (TimeRegistration) on /v1/time-registration/…, 51 (Project) on /v1/project/…, 98 (Task) on /v1/task/….

DomainIDinteger

The TimeRegistrationID (or, on the project / task endpoints, the ProjectID / TaskID). Refers to TimeRegistrationRead.TimeRegistrationID.

DomainGuidstring

The TimeRegistrationGUID (or the project / task GUID on those endpoints).

Format: uuid
IsIgnoredboolean

Never set by these endpoints.

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.

Path Parameters

taskIDinteger
Required

Route constraint :int.

Body

application/json
ExternalIDstring

The object's identifier in the external system.

Key from your own system. Uniqueness is not enforced.

NOT unique: two time registrations (or two projects, or two tasks) can carry the same ExternalID in the same external system. TimeLog does not deduplicate by external key — integrators must. Values over 250 characters are not rejected by validation (server outcome unknown).

ExternalSystemIDinteger

The external system the key belongs to.

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

Unknown ID fails with business rule 37045.

DomainTypeinteger

The object type: 147 (TimeRegistration) on /v1/time-registration/…, 51 (Project) on /v1/project/…, 98 (Task) on /v1/task/….

DomainIDinteger

The TimeRegistrationID (or, on the project / task endpoints, the ProjectID / TaskID).

Refers to TimeRegistrationRead.TimeRegistrationID.

DomainGuidstring

The TimeRegistrationGUID (or the project / task GUID on those endpoints).

IsIgnoredboolean

Never set by these endpoints.

Responses

Propertiesobject

Links a TimeLog object to its identifier in an external system (ERP, payroll, CRM …). One key per (object, external system).

Linksarray
Actionsobject[]