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 retry403
: 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 rules401
: 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 rules401
: 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]
Updated 6 months ago
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.