{"openapi":"3.0.0","info":{"title":"NL Official Documents API","description":"NL Official Documents API project represents the functionality to order documents from the KVK website.\n","version":"v0.1.0"},"servers":[{"url":"https://api.company.info/nl/organizations/official-documents","description":"Production Server"}],"security":[{"authToken":[]},{"jwtAuth":[]}],"tags":[{"name":"NL Official Documents API","description":"Calls related to the Official Documents API"}],"paths":{"/v1/orders":{"get":{"operationId":"getOrdersList","summary":"List previously placed orders","tags":["Order"],"description":"List previously placed orders\n","parameters":[{"name":"filter","in":"query","style":"deepObject","description":"Filter is used for filtering the orders based on `documentType`, `organizationID`, and `branchID`.","schema":{"type":"object","description":"Filter is used for filtering the orders based on `documentType`, `organizationID`, `branchID`, `status`, and `date`.","properties":{"organizationID":{"type":"string","example":"11111111"},"branchID":{"type":"string","example":"111111110011"},"status":{"type":"string","example":"done"},"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"date":{"type":"object","properties":{"from":{"type":"string","example":"2024-08-06"},"to":{"type":"string","example":"2024-08-07"}}}}}},{"name":"page","in":"query","style":"deepObject","description":"`size` defines the number of records to return in each page.\ndefault value: 10, maximum value: 20.\n<br>`number` specifies the page number.\"\n","schema":{"$ref":"#/components/schemas/Page"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderResultData"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"createOrder","summary":"Place a new document order","tags":["Order"],"description":"Place a new document order\n","requestBody":{"description":"The request body","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"orders"},"attributes":{"$ref":"#/components/schemas/OrderRequestAttributes"}}}}}}}},"responses":{"201":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderResultData"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/orders/{order_id}":{"get":{"operationId":"getOrder","summary":"Get a specific order","tags":["Order"],"description":"Get a specific order\n","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderResultData"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"runAnActivity","summary":"Retry a failed order activity","tags":["Order"],"description":"Retry a failed order activity\n","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The request body","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"orders"},"attributes":{"allOf":[{"type":"object","properties":{"activity":{"type":"string","enum":["order","convert"],"example":"order"}}}]}}}},"example":{"data":{"type":"orders","attributes":{"activity":"convert"}}}}}}},"responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"423"},"code":{"type":"string","example":"423"},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/orders/{order_id}/document":{"get":{"operationId":"downloadOrderDocument","summary":"Download a document from an order","tags":["Order"],"description":"Download a document from an order\n","parameters":[{"name":"Accept","required":true,"in":"header","schema":{"type":"string","example":"application/json"}},{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns PDF/HTML/JSON/ZIP","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"description":"Not Acceptable","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"406"},"code":{"type":"string","example":"406"},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested content-type is not supported"}}}}}}}}},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"423"},"code":{"type":"string","example":"423"},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/":{"get":{"operationId":"getSupportedDocuments","summary":"Discover supported documents for an organization","tags":["Document"],"description":"Discover supported documents for an organization\n","parameters":[{"name":"filter","in":"query","style":"deepObject","description":"Filter is used for filtering the supported documents based on `documentType`, `organizationID`, and `branchID`. `organizationID` is required.","schema":{"type":"object","description":"Filter is used to get the supported documents for the requested organization.","required":["organizationID"],"properties":{"organizationID":{"type":"string","example":"87654321"},"branchID":{"type":"string","example":"876543210001"},"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"}}}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"The organization ID this discovery result is for.","example":"33302047"},"type":{"type":"string","example":"documents"},"attributes":{"type":"object","properties":{"organizationID":{"type":"string","example":"33302047"},"branchID":{"type":"string","example":"000016450760"},"date":{"type":"string","format":"date-time","example":"2024-03-15T11:19:39+01:00"},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"mimeType":{"type":"string","enum":["application/pdf","application/json","application/zip","text/html"],"example":"text/html"},"price":{"type":"number","format":"float","example":2.95},"available":{"type":"boolean","example":true},"expectedTime":{"type":"integer","example":60},"description":{"type":"string","example":"Business Register Extract"},"productName":{"type":"string","enum":["directRelations","totalConcern","deedOfIncorporation","actOfIncorporation","amendmentOfArticlesOfAssociation","deedOfMerger","rectification","deedOfDivision","mostRecentArticlesOfAssociation","mergerDemergerProposal","demergerDeed","latestArticlesOfAssociation","articlesOfIncorporation","articlesOfAssociation"]},"productDate":{"type":"string","description":"Present for `standardStatute`, `maskedStatute` and `annualAccounts` orders. Can be a full date or a year.","oneOf":[{"type":"string","format":"date","example":"2023-12-06"},{"type":"string","pattern":"^\\d{4}$","example":"2023"}]},"maskedGDPR":{"type":"boolean","example":false}}}}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri-reference"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/documents":{"get":{"operationId":"getListOfDocuments","summary":"List available cached documents","tags":["Document"],"description":"List available cached documents\n","parameters":[{"name":"filter","in":"query","style":"deepObject","required":true,"description":"Filter is used for filtering the documents based on `type`, `organizationID`, and `branchID`.","schema":{"type":"object","required":["type","organizationID"],"description":"Filter is used for filtering the orders based on `type`, `organizationID`, `branchID` and `date`.","properties":{"organizationID":{"type":"string","example":"11111111"},"branchID":{"type":"string","example":"111111110011"},"type":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"date":{"type":"object","properties":{"from":{"type":"string","example":"2024-08-06"},"to":{"type":"string","example":"2024-08-07"}}}}}},{"name":"page","in":"query","style":"deepObject","description":"`size` defines the number of records to return in each page.\ndefault value: 10, maximum value: 20.\n<br>`number` specifies the page number.\"\n","schema":{"$ref":"#/components/schemas/Page"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-Id":{"description":"Unique request identifier","schema":{"type":"string","format":"uuid"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentResultData"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/documents/{document_id}":{"get":{"operationId":"downloadDocument","summary":"Download a cached document","tags":["Document"],"description":"Download a cached document\n","parameters":[{"name":"Accept","required":true,"in":"header","schema":{"type":"string","example":"application/json"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns PDF/HTML/JSON/ZIP","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"description":"Not Acceptable","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"406"},"code":{"type":"string","example":"406"},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested content-type is not supported"}}}}}}}}},"423":{"description":"Not Ready","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"423"},"code":{"type":"string","example":"423"},"title":{"type":"string","example":"failed on downloading document"},"detail":{"type":"string","example":"the requested document is not ready yet"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"authToken":{"description":"API Key Authentication","type":"apiKey","in":"header","name":"X-API-KEY"},"jwtAuth":{"description":"JWT Authentication","type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OrderRequestAttributes":{"title":"OrderRequestAttributes","description":"Attributes for placing a new document order. `branchID`, `productName` and\n`productDate` are only used with specific `documentType` values;\nthe server rejects combinations that are not allowed.\n","type":"object","required":["documentType","organizationID"],"properties":{"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"organizationID":{"type":"string","example":"33302047"},"branchID":{"type":"string","description":"Optional branch number. Not allowed for statute or concernRelations documents.","example":"000016450760"},"productName":{"type":"string","enum":["directRelations","totalConcern","deedOfIncorporation","actOfIncorporation","amendmentOfArticlesOfAssociation","deedOfMerger","rectification","deedOfDivision","mostRecentArticlesOfAssociation","mergerDemergerProposal","demergerDeed","latestArticlesOfAssociation","articlesOfIncorporation","articlesOfAssociation"],"description":"Required for `standardStatute`, `manualStatute`, `maskedStatute` and\n`concernRelations`.\n","example":"directRelationships"},"productDate":{"type":"string","description":"Present for `standardStatute`, `maskedStatute` and `annualAccounts` orders. Can be a full date or a year.","oneOf":[{"type":"string","format":"date","example":"2023-12-06"},{"type":"string","pattern":"^\\d{4}$","example":"2023"}]}}},"OrderResultData":{"title":"Order","type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","example":"01HS0SZQECSKQ8NV20391MZ0R1"},"type":{"type":"string","enum":["orders"],"example":"orders"},"attributes":{"type":"object","required":["documentType","organizationID","status","createdAt"],"properties":{"documentType":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"status":{"type":"string","enum":["pending","done","failed","cancelled"],"example":"pending"},"organizationID":{"type":"string","example":"33302047"},"branchID":{"type":"string","description":"Present when the order was placed for a specific branch.","example":"000016450760"},"productName":{"type":"string","enum":["directRelations","totalConcern","deedOfIncorporation","actOfIncorporation","amendmentOfArticlesOfAssociation","deedOfMerger","rectification","deedOfDivision","mostRecentArticlesOfAssociation","mergerDemergerProposal","demergerDeed","latestArticlesOfAssociation","articlesOfIncorporation","articlesOfAssociation"],"description":"Present for statute and concernRelations orders.","example":"directRelationships"},"productDate":{"type":"string","description":"Present for `standardStatute`, `maskedStatute` and `annualAccounts` orders. Can be a full date or a year.","oneOf":[{"type":"string","format":"date","example":"2023-12-06"},{"type":"string","pattern":"^\\d{4}$","example":"2023"}]},"mimeTypes":{"type":"array","description":"Available mime types for downloading this order's document. May\nbe absent when the order is still `pending` or has `failed`.\n","items":{"type":"string","enum":["application/pdf","application/json","application/zip","text/html"]},"example":["text/html","application/pdf","application/json","application/zip"]},"createdAt":{"type":"string","format":"date-time","example":"2024-03-15T11:19:39+01:00"}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri-reference"}}}}},"DocumentResultData":{"title":"Document","type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","example":"MDFLRVI5TldFMkdHN0I1Nkc1MENSQ1hRV0sIKeVgHoPvCxQswzN0i6m4VvYCkCC2fSf0XW3_51YXrA"},"type":{"type":"string","enum":["documents"],"example":"documents"},"attributes":{"type":"object","required":["type","organizationID","createdAt"],"properties":{"type":{"type":"string","enum":["standardExtract"],"example":"standardExtract"},"organizationID":{"type":"string","example":"33302047"},"branchID":{"type":"string","description":"Present when the cached document is for a specific branch.","example":"000016450760"},"productName":{"type":"string","enum":["directRelations","totalConcern","deedOfIncorporation","actOfIncorporation","amendmentOfArticlesOfAssociation","deedOfMerger","rectification","deedOfDivision","mostRecentArticlesOfAssociation","mergerDemergerProposal","demergerDeed","latestArticlesOfAssociation","articlesOfIncorporation","articlesOfAssociation"],"description":"Present for statute and concernRelations documents.","example":"directRelations"},"productDate":{"type":"string","description":"Present for `standardStatute`, `maskedStatute` and `annualAccounts` orders. Can be a full date or a year.","oneOf":[{"type":"string","format":"date","example":"2023-12-06"},{"type":"string","pattern":"^\\d{4}$","example":"2023"}]},"mimeTypes":{"type":"array","items":{"type":"string","enum":["application/pdf","application/json","application/zip","text/html"]},"example":["text/html","application/pdf","application/json","application/zip"]},"createdAt":{"type":"string","format":"date-time","example":"2024-03-15T11:19:39+01:00"},"upToDate":{"type":"boolean","example":true}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri-reference"}}}}},"PaginationLinks":{"title":"PaginationLinks","description":"JSON:API pagination `links`. The service emits bare string URIs (not\nthe `oneOf(string, object)` shape of the shared JSONAPI schema), so\nstrict client generators must model these as plain `string`.\n","type":"object","properties":{"first":{"type":"string","format":"uri-reference"},"last":{"type":"string","format":"uri-reference"},"next":{"type":"string","format":"uri-reference"},"prev":{"type":"string","format":"uri-reference"},"self":{"type":"string","format":"uri-reference"}}},"PaginationMeta":{"title":"PaginationMeta","type":"object","properties":{"totalPages":{"type":"integer","example":15},"totalResults":{"type":"integer","example":150}}},"Page":{"type":"object","properties":{"size":{"type":"integer","default":10,"description":"The number of records to return in each page."},"number":{"type":"integer","default":1,"description":"This parameter specifies the page number."}}},"JSONAPIErrorResponse":{"title":"JSON:API Error Response","type":"object","required":["errors"],"properties":{"errors":{"title":"An array of Error objects","type":"array","minItems":1,"items":{"type":"object","required":["status","code","title","detail"],"properties":{"status":{"description":"the HTTP status code applicable to this problem","type":"string","minLength":3,"maxLength":3},"code":{"description":"an application-specific error code. It can be the same as 'status'","type":"string"},"title":{"description":"a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization","type":"string"},"detail":{"description":"a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized","type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/JSONAPIErrorResponse"}}}}}}}