In this guide, we’ll cover how to map IDs between your data objects and Fragment tasks.
Having a sane and stable ID mapping between your data objects and Fragment tasks is important to avoid inconsistencies and to be able to retrieve the task from your existing system.

​
Requirements

​
Fragment task → existing object ID

When you’re creating a task in Fragment that is related to an object in your system, it’s recommended to push information like the object id to Fragment as a custom field. For example if your ticket is coming from Jira, you can push the Jira ticket ID to Fragment as a custom field.
task.json
{
    "fields": {
        "title": "Ticket 123",
        "url": "https://jira.com/tickets/123",
        "jira_ticket_id": 123, // Custom field
    }
}
This can help troubleshooting issues as well as enable operators to easily search for the object in your existing system.

​
Existing object → Fragment task ID

There are two main options to manage the ID mapping between your existing ticket system and Fragment tasks:
This method doesn’t require you to store the task ID in your system.
Generate a deterministic hash from your existing ticket ID (or other invariant fields that uniquely identify a ticket in a stable way). For example, if you have a ticket ID 123 in your existing system, you can generate a UID like this:
utils.py
import hashlib
import uuid

def generate_uuid(s: str) -> uuid.UUID:
    """Convert a string to a uid."""
    m = hashlib.md5()
    m.update(s.encode("utf-8"))
    return uuid.UUID(m.hexdigest())


generate_uuid("ticket#ID#123")
If you need to later retrieve the Fragment task from your existing ticket ID, ensure your hashing method is stable and deterministic. The same input should always generate the same UUID. Avoid using timestamps, random values, or other changing data in your hash generation.

​
2. Store the task ID in your system

This is a good option if you don’t want to generate a UUID for each task or if you want to explicitly store the task ID in your system. First, create the task on Fragment with a /POST request to the tasks endpoint. 
{
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "TODO",
    "due_at": "2025-09-11T12:00:00.000Z",
    "fields": { 
        "title": "Claim 123",
        "url": "https://backoffice.com/claims/123",
        "claim_id": "123", 
        "country": "FR"
    }
}
Then, store the task ID in your system in a custom field. For example, if you are using SQL, you can do the following: 
UPDATE claims SET fragment_task_uuid = '123e4567-e89b-12d3-a456-426614174000' WHERE id = 123;
This ensures that you can later retrieve the task from your existing ticket ID.

​
3. Combined approach

Using both options can also be useful as the UUID will be stable and the presence of the task ID in your system will let you know if the task has been created in Fragment.