Handling categories

Retrieve the existing categories to see if one already matches your needs, or create a new one

In our system, a Project needs to be linked to a category to make navigation easier for your user. You can retrieve the existing categories to add it to your Project, or create a new one matching your needs.

Authentication

cURL request

To be able to perform actions on our API, you need to be authenticated. To do this, use the following endpoint.

curl -XPOST 'https://primary-market-api-develop.tokeny.com.tokeny.com/auth/local' \
--header 'Content-Type: application/json' \
--data-raw '{
    "identifier":"[email protected]",
    "password": "my-password"
}'

Sample response

{
    "jwt": "<jwt>",
    "user": {
        "id": 1,
        "username": "Username",
        "email": "[email protected]",
        "provider": "local",
        "confirmed": true,
        "blocked": false,
        "role": {
            "id": 34,
            "name": "Projects creators",
            "description": "Authors of projects, authenticated with the permission to manage projects, categories, issuers and disclaimers.",
            "type": "projects_manager"
        },
        "created_at": "2021-03-17T16:14:14.286Z",
        "updated_at": "2021-03-17T16:16:00.097Z"
    }
}

jwt is the jwt token that you will need to perform the next operations

Troubleshooting

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": [
        {
            "messages": [
                {
                    "id": "Auth.form.error.invalid",
                    "message": "Identifier or password invalid."
                }
            ]
        }
    ],
    "data": [
        {
            "messages": [
                {
                    "id": "Auth.form.error.invalid",
                    "message": "Identifier or password invalid."
                }
            ]
        }
    ]
}

The status code can be either:

  • 400: one of the specified credential is wrong, please check them again. In case you lost your password, please contact [email protected]
  • 401: you are not allowed to connect to the API. If you think it is a mistake, please contact your administrator or [email protected]

Retrieve the existing categories

cURL

If categories were previously created in our system, you can retrieve them easily with the following request.

curl -XGET 'https://primary-market-api-develop.tokeny.com.tokeny.com/categories' \
--header 'Authorization: Bearer <jwt>'

jwt is the authentication token you received on the Authentication step.

Sample response

[
    {
        "id": 1,
        "name": "Equity",
        "published_at": "2020-12-02T14:57:47.510Z",
        "created_at": "2020-12-02T14:57:42.007Z",
        "updated_at": "2020-12-02T14:57:47.528Z"
    },
    {
        "id": 2,
        "name": "Bonds and Loans",
        "published_at": "2020-12-02T14:58:07.186Z",
        "created_at": "2020-12-02T14:58:04.300Z",
        "updated_at": "2020-12-02T14:58:07.203Z"
    },
    {
        "id": 3,
        "name": "Real estate",
        "published_at": "2020-12-02T14:58:17.012Z",
        "created_at": "2020-12-02T14:58:15.373Z",
        "updated_at": "2020-12-02T14:58:17.030Z"
    }
]

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

  • 401: your authentication token is invalid or has expired. Please go back to the Authentication step and retry
  • 403: you are not authorized to access this resource. If you think this is an error, contact your administrator or [email protected]

Create a new category

cURL

If no existing categories match your needs, you can create a new one using the following request.

curl --location --request POST 'https://primary-market-api-develop.tokeny.com/categories' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "<category_name>"
}'

jwt is the authentication token you retrieved in the Authentication step.
category_name is the name you want to give to your new category.

Sample response

{
    "id": 34,
    "name": "Funds",
    "published_at": "2021-03-17T16:56:02.711Z",
    "created_at": "2021-03-17T16:56:02.721Z",
    "updated_at": "2021-03-17T16:56:02.721Z"
}

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

  • 400: you forgot to specify a mandatory field or the field doesn't match the validation rules
  • 401: your authentication token is invalid. Go back to the Authentication step and retry.
  • 403: you are not allowed to create categories. If you think this is an error, contact your administrator or [email protected]

Rename a category

cURL

If you need to rename a category, use the following request.

curl -XPUT 'https://primary-market-api-develop.tokeny.com/categories/<category_id>' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "<new_category_name>"
}'

jwt is the authentication token retrieved in the Authenticate step
category_id is the unique identifier of the category, retrieved though the "Retrieve the existing categories" step, or the "Create new category" step.
new_category_name is the new name that you want to give to your category.

Sample response

{
    "id": 34,
    "name": "Fund",
    "published_at": "2021-03-17T16:56:02.711Z",
    "created_at": "2021-03-17T16:56:02.721Z",
    "updated_at": "2021-03-18T09:09:46.630Z"
}

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

  • 400: you forgot to specify a mandatory field or the field doesn't match the validation rules
  • 401: your authentication token is invalid. Go back to the Authentication step and retry.
  • 403: you are not allowed to create categories. If you think this is an error, contact your administrator or [email protected]

What’s Next

Once you're set with Categories, you can go on to create the issuer details of the project. If you already are set with Issuers, you can go on and set up the disclaimers, or directly to the creation of your project.