> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/api-reference/tracr-api/register_rough.md).

# Register rough

> **Please note**
>
> * Rough diamonds can only be registered on Tracr by producers and manufacturers. Retailers should use the transfer endpoints to accept polished diamonds from manufacturers on the Tracr network.
> * Rough diamonds registered via the API won't appear in the Integration Monitoring section of the Tracr Portal.

## Register a De Beers diamond

To register a diamond from a De Beers sight box, call the `/diamonds/rough/create` endpoint with the De Beers box ID, along with the sight year and number:

Call `POST /diamonds/rough/create`

{% tabs %}
{% tab title="Request" %}

```json
{
    "box_id": "demo_box",
    "participant_id": "demo_1",
    "participant_timestamp": "2024-05-31T11:38:38.206655+00:00",
    "rough": {
        "carats": 2.16
    },
    "sight_no": 2,
    "sight_year": 2024
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "assurance_level": "assured",
    "box_id": "demo_box",
    "current_stage": "rough",
    "diamond_id": "wemz3zvg7cvr5uugivhib1z0",
    "entity_specific_tags": {},
    "id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
    "is_current": true,
    "lifecycle_state": "rough",
    "participant_id": "demo_1",
    "participant_timestamp": "2024-05-31T11:38:38.206655+00:00",
    "polished": {},
    "possession_state": "held",
    "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
    "provenance": {
        "provenance_name": "",
        "provenance_type": "Entity",
        "is_locked": true,
        "is_country_code_available": true
    },
    "rough": {
        "carats": 2.16
    },
    "schema_version": "1.1.0",
    "sight_no": 2,
    "sight_year": 2024,
    "system_timestamp": "2024-05-31T11:41:25.525000+00:00",
    "verification_description": "verified record",
    "verification_status": "Verified",
    "version_id": "hyfyv1o484li32aof6af5fbr",
    "verification_status_modified_at": "2024-05-31T11:41:26.068930+00:00"
}
```

{% endtab %}
{% endtabs %}

If the registration failed then the reason for the failure will be given in the response, for example:

```json
{
    "message": "Diamond is not unique"
}
```

## Register a diamond from another producer

Non-De Beers diamonds are sent from the producer's Tracr instance as shipments. These will appear in the Inbound Shipments screen of the Tracr Portal when ready.

The shipment needs to be accepted before any of the diamonds can be registered - see [Transfer In](https://gitlab.com/tracr/pcs/platform/pcs/-/blob/gitbook/docs/tracr-api/o2w4ljppvzatu-transfer-in/README.md) for how to accept a shipment of rough diamonds.

> **Important:** When uploading diamonds, instead of providing the box details from De Beers (such as sight, year, and box ID), you will need to provide the **Shipment ID** in the “box\_id” column. The **Shipment ID** appears on the **Active** tab, next to the **Sender**.

Once accepted, call the `/diamonds/rough/create` endpoint, passing the shipment ID assigned by Tracr as the box ID:

Call `POST /diamonds/rough/create`

{% tabs %}
{% tab title="First Tab" %}

```json
{
    "box_id": "b66ei4prxlp3fx1lwd2zps7x",
    "participant_id": "erp_id_123456",
    "participant_timestamp": "2023-03-31T18:23:08.283000+00:00",
    "rough": {
        "carats": 1.42
    }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "assurance_level": "assured",
    "box_id": "b66ei4prxlp3fx1lwd2zps7x",
    "current_stage": "rough",
    "diamond_id": "c4tr1cr9hcozhhy0czqeywd1",
    "entity_specific_tags": {},
    "id": "df5a4c50-5a0e-425c-83c1-86007bca8ef4",
    "is_current": true,
    "lifecycle_state": "rough",
    "participant_id": "erp_id_123456",
    "participant_timestamp": "2024-05-31T10:27:56.283000+00:00",
    "polished": {},
    "possession_state": "held",
    "producer_uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "provenance": {
        "provenance_name": "",
        "provenance_type": "Country",
        "is_locked": true,
        "is_country_code_available": true
    },
    "rough": {
        "carats": 1.42
    },
    "schema_version": "1.1.0",
    "system_timestamp": "2024-05-31T10:28:33.284000+00:00",
    "verification_description": "verified record",
    "verification_status": "Verified",
    "version_id": "cnj0gs40aszwepxtn7j41btj",
    "verification_status_modified_at": "2024-05-31T10:28:33.775828+00:00"
}
```

{% endtab %}
{% endtabs %}

Tracr checks the weight and number of diamonds registered against each shipment. If these don't align then an error will be returned:

```json
{
    "message": "Shipment checks failed. The diamond is heavier than the heaviest diamond in the shipment."
}
```

## Register a diamond as a producer

Diamond producers register rough diamonds via the same endpoint, but can specify provenance information when doing so:

Call `POST /diamonds/rough/create`

{% tabs %}
{% tab title="Request" %}

```json
{
    "box_id": "demo_rough_box",
    "participant_id": "rough_1",
    "participant_timestamp": "2024-05-31T11:20:12.015648+00:00",
    "provenance": {
        "provenance_name": "BW",
        "provenance_type": "Country"
    },
    "rough": {
        "carats": 2.57
    }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "assurance_level": "assured",
    "box_id": "demo_rough_box",
    "current_stage": "rough",
    "diamond_id": "gy9zacqpt64rfm5l9aj8fdgc",
    "entity_specific_tags": {},
    "id": "e1fda76b-e46e-4956-aca8-b18577ac25e2",
    "is_current": true,
    "lifecycle_state": "rough",
    "participant_id": "rough_1",
    "participant_timestamp": "2024-05-31T11:20:12.015648+00:00",
    "polished": {},
    "possession_state": "held",
    "producer_uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "provenance": {
        "provenance_name": "BW",
        "provenance_type": "Country",
        "is_locked": false,
        "is_country_code_available": true
    },
    "rough": {
        "carats": 2.57
    },
    "schema_version": "1.1.0",
    "system_timestamp": "2024-05-31T11:22:29.647000+00:00",
    "verification_description": "verified record",
    "verification_status": "Verified",
    "version_id": "fq94xt0wh4yhls5c82msr6p8",
    "verification_status_modified_at": "2024-05-31T11:22:30.203316+00:00"
}
```

{% endtab %}
{% endtabs %}

> **An important note regarding provenance**
>
> Only a diamond producer can declare the provenance of a diamond. Once a manufacturer registers a rough diamond in Tracr, the provenance is updated by Tracr after verification of the traceability data.

## Upload additional assets

Once the diamond has been created, additional assets can be attached.

Tracr can append the following files:

* Scan
* Images
* Videos

For example, to add an image of the rough diamond:

Call `POST /diamonds/wemz3zvg7cvr5uugivhib1z0/files/image`

{% tabs %}
{% tab title="Form-data" %}

| Key         | Value               |
| ----------- | ------------------- |
| file        | demo\_1\_rough.jpeg |
| description | Rough Image         |
| image\_type | default             |

```json
Content-Type: multipart/form-data; boundary=8317046c4dac35881b333a4c43b41d64
--8317046c4dac35881b333a4c43b41d64
Content-Disposition: form-data; name="description"
Rough Image

--8317046c4dac35881b333a4c43b41d64
Content-Disposition: form-data; name="image_type"
default

--8317046c4dac35881b333a4c43b41d64
Content-Disposition: form-data; name="file"; filename="demo_rough_1.jpg"
```

{% endtab %}

{% tab title="Reponse" %}

```json
{
  "hash":"cf02abefba1b4837b35f45b7f578251046b3bb100d129ff5adc77342d7e0f8a9"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tracr.com/api-reference/tracr-api/register_rough.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
