HTTP methods, headers, and status codes

This chapter summarises the HTTP methods, status codes, and headers that can be used to call the Investment API and lists response options.

HTTP methods

HTTP method	Purpose
`GET`	Returns a list of resources or a single resource, depending on the call.
`POST`	Creates a new resource synchronously and returns `201 Created` or creates a new resource and starts the asynchronous processing required to complete the creation. In this case return code is `202 Accepted`.
`PATCH`	Updates a resource's information.
`DELETE`	Deletes an instance of a resource where allowed and returns `204 No Content`.

NOTE

Some resources may allow only partial data change.

There are some mandatory headers for each call.

Header	Purpose	Allowed values
`accept`	Specification of media types that are accepted for the response.	`application/json` `application/pdf`
`authorization`	Bearer access token.	`Bearer: <your access token>`
`content-length`	Size of the entity request body.	-
`content-type`	Media type of the entity request body.	`application/json` `application/x-www-form-urlencoded`
`idempotency-key`	Key for idempotency protection.
`upvest-client-id`	Tenant ID	-
`upvest-api-version`	Major version of the API to request.	1

NOTE

content-length and content-type headers required only for requests that contain a request body.
idempotency-key required only for POST and PATCH operations.
upvest-api-version is optional and has a default value of 1. (Note: you should not place quotes around this value despite it being defined as being a string)

We return the following HTTP status codes from our endpoints.

HTTP status code	Status message	Purpose
200	OK	The call has been completed.
201	Created	The new resource has been fully created.
202	Accepted	The request processing has been started succesfully but will be completed asynchronously.
204	No Content	The resource has been succesfully deleted.

HTTP status code	Status message	Purpose
400	Bad Request	The incoming request was malformed.
401	Unauthorized	The caller could not be authenticated.
403	Forbidden	The caller is not allowed to take this action.
404	Not Found	The specified resource was not found.
405	Method Not Allowed	The requested HTTP method is not allowed on this resource.
406	Not Acceptable	The resource does not have a current representation that would be acceptable to the user agent. The "Accept" header defined an unsupported value.
426	Upgrade Required	The request for an older version of the API after it has been retired.
429	Too Many Requests	The caller was throttled due to exceeding the call quota.

HTTP status code	Status message	Purpose
500	Internal Server Error	Something unexpectedly went wrong with the service. Please reach out to our support.
503	Service Unavailable	The receiving service could not be reached. Please try again.