> 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.