> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/v2024-01-31/api/entities/post-entities/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Create an entity POST https://api.sandbox.monite.com/v1/entities Content-Type: application/json Create a new entity from the specified values. Reference: https://docs.monite.com/api/entities/post-entities ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.sandbox.monite.com/v1` (sandbox, default) - `https://api.monite.com/v1` (eu_production) - `https://us.api.monite.com/v1` (na_production) ## Request ### Headers - `x-monite-version` (string, required) ### Body (application/json) This endpoint expects an object. - `address` (EntityAddressSchema, required) — An address description of the entity - `email` (string, required) — An official email address of the entity - `type` (enum, required) — A type for an entity - Allowed values: `individual`, `organization` - `individual` (IndividualSchema, optional) — A set of meta data describing the individual - `organization` (OrganizationSchema, optional) — A set of meta data describing the organization - `phone` (string, optional) — The contact phone number of the entity. Required for US organizations to use payments. - `registration_authority` (string, optional) — (Germany only) The name of the local district court (_Amtsgericht_) where the entity is registered. Required if `registration_number` is provided. - `registration_number` (string, optional) — (Germany only) The entity's commercial register number (_Handelsregisternummer_) in the German Commercial Register, if available. - `tax_id` (string, optional) — The entity's taxpayer identification number or tax ID. This field is required for entities that are non-VAT registered. - `website` (string, optional) — A website of the entity ## Response ### 201 Successful Response - `EntityResponse` - `type`: `individual` - `address` (EntityAddressResponseSchema, required) — An address description of the entity - `created_at` (datetime, required) — UTC datetime - `id` (string, required) — UUID entity ID - `individual` (IndividualResponseSchema, required) — A set of metadata describing an individual - `status` (enum, required) — record status, 'active' by default - Allowed values: `active`, `deleted` - `updated_at` (datetime, required) — UTC datetime - `email` (string, optional) — An official email address of the entity - `logo` (FileSchema2, optional) — A logo image of the entity - `phone` (string, optional) — A phone number of the entity - `registration_authority` (string, optional) — (Germany only) The name of the local district court (_Amtsgericht_) where the entity is registered. Required if `registration_number` is provided. - `registration_number` (string, optional) — (Germany only) The entity's commercial register number (_Handelsregisternummer_) in the German Commercial Register, if available. - `tax_id` (string, optional) — The entity's taxpayer identification number or tax ID. This field is required for entities that are non-VAT registered. - `website` (string, optional) — A website of the entity - `type`: `organization` - `address` (EntityAddressResponseSchema, required) — An address description of the entity - `created_at` (datetime, required) — UTC datetime - `id` (string, required) — UUID entity ID - `organization` (OrganizationResponseSchema, required) — A set of metadata describing an organization - `status` (enum, required) — record status, 'active' by default - Allowed values: `active`, `deleted` - `updated_at` (datetime, required) — UTC datetime - `email` (string, optional) — An official email address of the entity - `logo` (FileSchema2, optional) — A logo image of the entity - `phone` (string, optional) — A phone number of the entity - `registration_authority` (string, optional) — (Germany only) The name of the local district court (_Amtsgericht_) where the entity is registered. Required if `registration_number` is provided. - `registration_number` (string, optional) — (Germany only) The entity's commercial register number (_Handelsregisternummer_) in the German Commercial Register, if available. - `tax_id` (string, optional) — The entity's taxpayer identification number or tax ID. This field is required for entities that are non-VAT registered. - `website` (string, optional) — A website of the entity ## Errors ### 400 Post Entities Request Bad Request Error Bad Request - `error` (ErrorSchema, required) ### 403 Post Entities Request Forbidden Error Forbidden - `error` (ErrorSchema, required) ### 422 Post Entities Request Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ### 500 Post Entities Request Internal Server Error Internal Server Error - `error` (ErrorSchema, required) ## Types ### EntityAddressSchema A schema represents address info of the entity - `city` (string, required) — A city (a full name) where the entity is registered - `country` (enum, required) — A country name (as ISO code) where the entity is registered - Allowed values: `AF`, `AX`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, `AR`, `AM`, `AW`, `AU`, `AT`, `AZ`, `BS`, `BH`, `BD`, `BB`, `BY`, `BE`, `BZ`, `BJ`, `BM`, `BT`, `BO`, `BA`, `BW`, `BV`, `BR`, `IO`, `BN`, `BG`, `BF`, `BI`, `KH`, `CM`, `CA`, `IC`, `CV`, `KY`, `CF`, `EA`, `TD`, `CL`, `CN`, `CX`, `CC`, `CO`, `KM`, `CG`, `CD`, `CK`, `CR`, `CI`, `HR`, `CU`, `CY`, `CZ`, `DK`, `DJ`, `DM`, `DO`, `EC`, `EG`, `SV`, `GQ`, `ER`, `EE`, `SZ`, `ET`, `FK`, `FO`, `FJ`, `FI`, `FR`, `GF`, `PF`, `TF`, `GA`, `GM`, `GE`, `DE`, `GH`, `GI`, `GR`, `GL`, `GD`, `GP`, `GU`, `GT`, `GG`, `GN`, `GW`, `GY`, `HT`, `HM`, `VA`, `HN`, `HK`, `HU`, `IS`, `IN`, `ID`, `IR`, `IQ`, `IE`, `IM`, `IL`, `IT`, `JM`, `JP`, `JE`, `JO`, `KZ`, `KE`, `KI`, `KP`, `KR`, `KW`, `KG`, `LA`, `LV`, `LB`, `LS`, `LR`, `LY`, `LI`, `LT`, `LU`, `MO`, `MG`, `MW`, `MY`, `MV`, `ML`, `MT`, `MH`, `MQ`, `MR`, `MU`, `YT`, `MX`, `FM`, `MD`, `MC`, `MN`, `ME`, `MS`, `MA`, `MZ`, `MM`, `NA`, `NR`, `NP`, `NL`, `AN`, `NC`, `NZ`, `NI`, `NE`, `NG`, `NU`, `NF`, `MP`, `MK`, `NO`, `OM`, `PK`, `PW`, `PS`, `PA`, `PG`, `PY`, `PE`, `PH`, `PN`, `PL`, `PT`, `PR`, `QA`, `RE`, `RO`, `RU`, `RW`, `SH`, `KN`, `LC`, `PM`, `VC`, `WS`, `SM`, `ST`, `SA`, `SN`, `RS`, `SC`, `SL`, `SG`, `SK`, `SI`, `SB`, `SO`, `ZA`, `SS`, `GS`, `ES`, `LK`, `SD`, `SR`, `SJ`, `SE`, `CH`, `SY`, `TW`, `TJ`, `TZ`, `TH`, `TL`, `TG`, `TK`, `TO`, `TT`, `TN`, `TR`, `TM`, `TC`, `TV`, `UG`, `UA`, `AE`, `GB`, `US`, `UM`, `UY`, `UZ`, `VU`, `VE`, `VN`, `VG`, `VI`, `WF`, `EH`, `YE`, `ZM`, `ZW`, `BL`, `BQ`, `CW`, `MF`, `SX` - `line1` (string, required) — A street where the entity is registered - `postal_code` (string, required) — A postal code of the address where the entity is registered - `line2` (string, optional) — An alternative street used by the entity - `state` (string, optional) — State, county, province, prefecture, region, or similar component of the entity's address. For US entities, `state` is required and must be a two-letter [USPS state abbreviation](https://pe.usps.com/text/pub28/28apb.htm), for example, NY or CA. ### IndividualSchema A schema contains metadata for an individual - `first_name` (string, required) — A first name of an individual - `last_name` (string, required) — A last name of an individual - `date_of_birth` (string, optional) - `id_number` (string, optional) - `ssn_last_4` (string, optional) — The last four digits of the individual's Social Security number - `title` (string, optional) — A title of an individual ### OrganizationSchema A schema contains metadata for an organization - `legal_name` (string, required) — The legal name of the organization. If this organization will use Monite payment rails, this name must be up to 100 characters long, otherwise it can be up to 255 characters long. - `business_structure` (enum, optional) — Business structure of the company - Allowed values: `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`, `sole_proprietorship`, `single_member_llc`, `multi_member_llc`, `private_partnership`, `unincorporated_association`, `public_partnership` - `directors_provided` (boolean, optional) - `executives_provided` (boolean, optional) - `legal_entity_id` (string, optional) — A code which identifies uniquely a party of a transaction worldwide - `owners_provided` (boolean, optional) - `representative_provided` (boolean, optional) ### EntityAddressResponseSchema A schema represents address info of the entity - `city` (string, required) — A city (a full name) where the entity is registered - `country` (enum, required) — A country name (as ISO code) where the entity is registered - Allowed values: `AF`, `AX`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, `AR`, `AM`, `AW`, `AU`, `AT`, `AZ`, `BS`, `BH`, `BD`, `BB`, `BY`, `BE`, `BZ`, `BJ`, `BM`, `BT`, `BO`, `BA`, `BW`, `BV`, `BR`, `IO`, `BN`, `BG`, `BF`, `BI`, `KH`, `CM`, `CA`, `IC`, `CV`, `KY`, `CF`, `EA`, `TD`, `CL`, `CN`, `CX`, `CC`, `CO`, `KM`, `CG`, `CD`, `CK`, `CR`, `CI`, `HR`, `CU`, `CY`, `CZ`, `DK`, `DJ`, `DM`, `DO`, `EC`, `EG`, `SV`, `GQ`, `ER`, `EE`, `SZ`, `ET`, `FK`, `FO`, `FJ`, `FI`, `FR`, `GF`, `PF`, `TF`, `GA`, `GM`, `GE`, `DE`, `GH`, `GI`, `GR`, `GL`, `GD`, `GP`, `GU`, `GT`, `GG`, `GN`, `GW`, `GY`, `HT`, `HM`, `VA`, `HN`, `HK`, `HU`, `IS`, `IN`, `ID`, `IR`, `IQ`, `IE`, `IM`, `IL`, `IT`, `JM`, `JP`, `JE`, `JO`, `KZ`, `KE`, `KI`, `KP`, `KR`, `KW`, `KG`, `LA`, `LV`, `LB`, `LS`, `LR`, `LY`, `LI`, `LT`, `LU`, `MO`, `MG`, `MW`, `MY`, `MV`, `ML`, `MT`, `MH`, `MQ`, `MR`, `MU`, `YT`, `MX`, `FM`, `MD`, `MC`, `MN`, `ME`, `MS`, `MA`, `MZ`, `MM`, `NA`, `NR`, `NP`, `NL`, `AN`, `NC`, `NZ`, `NI`, `NE`, `NG`, `NU`, `NF`, `MP`, `MK`, `NO`, `OM`, `PK`, `PW`, `PS`, `PA`, `PG`, `PY`, `PE`, `PH`, `PN`, `PL`, `PT`, `PR`, `QA`, `RE`, `RO`, `RU`, `RW`, `SH`, `KN`, `LC`, `PM`, `VC`, `WS`, `SM`, `ST`, `SA`, `SN`, `RS`, `SC`, `SL`, `SG`, `SK`, `SI`, `SB`, `SO`, `ZA`, `SS`, `GS`, `ES`, `LK`, `SD`, `SR`, `SJ`, `SE`, `CH`, `SY`, `TW`, `TJ`, `TZ`, `TH`, `TL`, `TG`, `TK`, `TO`, `TT`, `TN`, `TR`, `TM`, `TC`, `TV`, `UG`, `UA`, `AE`, `GB`, `US`, `UM`, `UY`, `UZ`, `VU`, `VE`, `VN`, `VG`, `VI`, `WF`, `EH`, `YE`, `ZM`, `ZW`, `BL`, `BQ`, `CW`, `MF`, `SX` - `line1` (string, required) — A street where the entity is registered - `postal_code` (string, required) — A postal code of the address where the entity is registered - `line2` (string, optional) — An alternative street used by the entity - `state` (string, optional) — A state in a country where the entity is registered ### IndividualResponseSchema Contains data specific to entities of the `individual` type. - `first_name` (string, required) — A first name of an individual - `last_name` (string, required) — A last name of an individual - `date_of_birth` (string, optional) - `id_number` (string, optional) - `ssn_last_4` (string, optional) — The last four digits of the individual's Social Security number - `title` (string, optional) — A title of an individual ### FileSchema2 Represents a file (such as a PDF invoice) that was uploaded to Monite. - `id` (string, required) — A unique ID of this file. - `created_at` (datetime, required) — UTC date and time when this file was uploaded to Monite. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. - `file_type` (string, required) — The type of the business object associated with this file. - `md5` (string, required) — The MD5 hash of the file. - `mimetype` (string, required) — The file's [media type](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types). - `name` (string, required) — The original file name (if available). - `region` (string, required) — Geographical region of the data center where the file is stored. - `size` (integer, required) — The file size in bytes. - `url` (string, required) — The URL to download the file. - `pages` (list of PageSchema, optional) — If the file is a PDF document, this property contains individual pages extracted from the file. Otherwise, an empty array. - `previews` (list of PreviewSchema, optional) — Preview images generated for this file. There can be multiple images with different sizes. ### OrganizationResponseSchema Contains data specific to entities of the `organization` type. - `legal_name` (string, required) — The legal name of the organization. - `business_structure` (enum, optional) — Business structure of the company - Allowed values: `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`, `sole_proprietorship`, `single_member_llc`, `multi_member_llc`, `private_partnership`, `unincorporated_association`, `public_partnership` - `directors_provided` (boolean, optional) - `executives_provided` (boolean, optional) - `legal_entity_id` (string, optional) — A code which identifies uniquely a party of a transaction worldwide - `owners_provided` (boolean, optional) - `representative_provided` (boolean, optional) ### ErrorSchema - `message` (string, required) ### ValidationError - `loc` (list of ValidationErrorLocItem, required) - `msg` (string, required) - `type` (string, required) ### PageSchema When a PDF document is uploaded to Monite, it extracts individual pages from the document and saves them as PNG images. This object contains the image and metadata of a single page. - `id` (string, required) — A unique ID of the image. - `mimetype` (string, required) — The [media type](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types) of the image. - `number` (integer, required) — The page number in the PDF document, from 0. - `size` (integer, required) — Image file size, in bytes. - `url` (string, required) — The URL to download the image. ### PreviewSchema A preview image generated for a file. - `height` (integer, required) — The image height in pixels. - `url` (string, required) — The image URL. - `width` (integer, required) — The image width in pixels. ### ValidationErrorLocItem ## Examples **Request** ```json { "address": { "city": "city", "country": "AF", "line1": "line1", "postal_code": "postal_code" }, "email": "email", "type": "individual" } ``` **Response** ```json { "type": "individual", "address": { "city": "city", "country": "AF", "line1": "line1", "postal_code": "postal_code", "line2": "line2", "state": "state" }, "created_at": "2024-01-15T09:30:00Z", "id": "id", "individual": { "first_name": "first_name", "last_name": "last_name", "date_of_birth": "date_of_birth", "id_number": "id_number", "ssn_last_4": "ssn_last_4", "title": "title" }, "status": "active", "updated_at": "2024-01-15T09:30:00Z", "email": "email", "logo": { "id": "id", "created_at": "2024-01-15T09:30:00Z", "file_type": "payables", "md5": "31d1a2dd1ad3dfc39be849d70a68dac0", "mimetype": "application/pdf", "name": "invoice.pdf", "region": "eu-central-1", "size": 24381, "url": "https://bucketname.s3.amazonaws.com/12345/67890.pdf", "pages": [ { "id": "id", "mimetype": "image/png", "number": 0, "size": 21972, "url": "https://bucket.s3.amazonaws.com/123/456.png" } ], "previews": [ { "height": 400, "url": "https://bucketname.s3.amazonaws.com/1/2/3.png", "width": 200 } ] }, "phone": "phone", "registration_authority": "registration_authority", "registration_number": "registration_number", "tax_id": "tax_id", "website": "website" } ``` **SDK Code** ```python import requests url = "https://api.sandbox.monite.com/v1/entities" payload = { "address": { "city": "city", "country": "AF", "line1": "line1", "postal_code": "postal_code" }, "email": "email", "type": "individual" } headers = { "x-monite-version": "2024-01-31", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.sandbox.monite.com/v1/entities'; const options = { method: 'POST', headers: { 'x-monite-version': '2024-01-31', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"address":{"city":"city","country":"AF","line1":"line1","postal_code":"postal_code"},"email":"email","type":"individual"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sandbox.monite.com/v1/entities" payload := strings.NewReader("{\n \"address\": {\n \"city\": \"city\",\n \"country\": \"AF\",\n \"line1\": \"line1\",\n \"postal_code\": \"postal_code\"\n },\n \"email\": \"email\",\n \"type\": \"individual\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-monite-version", "2024-01-31") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.sandbox.monite.com/v1/entities") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-monite-version"] = '2024-01-31' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"address\": {\n \"city\": \"city\",\n \"country\": \"AF\",\n \"line1\": \"line1\",\n \"postal_code\": \"postal_code\"\n },\n \"email\": \"email\",\n \"type\": \"individual\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sandbox.monite.com/v1/entities") .header("x-monite-version", "2024-01-31") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"address\": {\n \"city\": \"city\",\n \"country\": \"AF\",\n \"line1\": \"line1\",\n \"postal_code\": \"postal_code\"\n },\n \"email\": \"email\",\n \"type\": \"individual\"\n}") .asString(); ``` ```php request('POST', 'https://api.sandbox.monite.com/v1/entities', [ 'body' => '{ "address": { "city": "city", "country": "AF", "line1": "line1", "postal_code": "postal_code" }, "email": "email", "type": "individual" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'x-monite-version' => '2024-01-31', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.sandbox.monite.com/v1/entities"); var request = new RestRequest(Method.POST); request.AddHeader("x-monite-version", "2024-01-31"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"address\": {\n \"city\": \"city\",\n \"country\": \"AF\",\n \"line1\": \"line1\",\n \"postal_code\": \"postal_code\"\n },\n \"email\": \"email\",\n \"type\": \"individual\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-monite-version": "2024-01-31", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "address": [ "city": "city", "country": "AF", "line1": "line1", "postal_code": "postal_code" ], "email": "email", "type": "individual" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sandbox.monite.com/v1/entities")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```