Companies House Assistant API
Obtain a session in Deluge, send it on each connector call, and read the response. This reference is public.
Authentication
Every call goes to https://connector.zepartner.net. Create a session from a Deluge script inside Zoho CRM, then send data.session.sessionId as the x-zep-session-id header. The function takes no arguments. The session lasts 24 hours. Cache it until data.session.exp, which is a unix epoch value in milliseconds. The examples on this page assume sessionId is already set.
sessionResult = itlukcha.generate_zep_session();
sessionId = sessionResult.get("data").get("session").get("sessionId");{
"success": true,
"data": {
"session": {
"crmOrgId": "orgXXXXXXXXXX",
"extensionName": "ZE Companies House Assistant",
"userId": "0000000000000000000",
"userName": "Example User",
"userEmail": "user@example.com",
"createdAt": 1790618117000,
"exp": 1790704517000,
"sessionId": "<session-id>"
}
},
"error": null
}The session map can also include organisation data, the current user, and the user list. A failed call returns success: false, data: null, and an error map.
x-zep-session-id: <session-id>With detailed: true, read the HTTP status and the JSON body from the invokeurl map.
responseCode = response.get("responseCode");
body = response.get("responseText").toMap();A valid session is required on every call. Lookup and refresh calls also require an active ZE Companies House Assistant subscription. Companies House calls use the API key saved in the organisation’s settings. Leave that key off the request.
A successful Companies House call uses 1 credit. Advanced search uses ceil(size / 100). Connected companies uses 1 credit for each upstream call, up to maxCalls. A Companies House 404 or 429 is not charged. Reading credits, reading usage, and the settings calls do not use a credit.
An invalid or expired session is HTTP 401: { "success": false, "data": null, "error": "Session expired" }. The error text can also be Invalid sessionId, Invalid session claims, Session organization mismatch, or Invalid session. A request with no credentials returns { "ERROR": "Unauthorized" }. On HTTP 401, create a new session and retry once.
Companies House proxy failures use { "success": false, "ERROR": "<message>" }. Typical statuses are 400 for a missing key or a bad id, 401 when Companies House rejects the key, 402 when credits are used up, 404 when the record is missing, 429 for a rate limit (the response includes Retry-After), 500 when a credit could not be deducted, and 502 when the upstream body could not be read. Company search and advanced search report a missing key, an inactive subscription, or an upstream failure as HTTP 500 with { "ERROR": "<message>" }.
Credits
Remaining credits
Read the organisation’s remaining search allowance and the plan month. This call does not deduct a credit and does not require the subscription to be active.
GET /ze-companies-house-assistant/credits
Use data.Remaining_Credits before a search. The row can include other stored settings columns. Read configuration from GET /settings.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/credits";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"data": {
"CRM_Org_ID": "orgXXXXXXXXXX",
"Current_Plan_Code": "zecha_bronze",
"Current_Month_and_Year": "September_2026",
"Remaining_Credits": 487
}
}Credit usage
Monthly usage for CRM Administrators. The session user’s CRM profile name must be Administrator. This call does not deduct a credit.
GET /ze-companies-house-assistant/credit-usage
Parameters
monthQuery- YYYY-MM. Defaults to the current UTC month. Any other value returns HTTP 400.
sourceQuery- background or interactive. Any other value is ignored.
limitQuery- Page size. Default 50, clamped to 1–100.
offsetQuery- Zero-based offset. Default 0, clamped to 0–10000.
A profile other than Administrator returns HTTP 403 with code ADMIN_REQUIRED. An inactive subscription returns HTTP 402. If the usage table is missing, the call still returns HTTP 200 with usageTableReady false and empty arrays.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/credit-usage?month=2026-09&limit=50&offset=0";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"data": {
"month": "2026-09",
"usageTableReady": true,
"remainingCredits": 487,
"totals": { "credits": 13, "background": 8, "interactive": 5 },
"byAction": [
{ "action": "Company search", "source": "interactive", "credits": 5, "calls": 5 }
],
"byUser": [
{
"userId": "0000000000000000000",
"userName": "Example User",
"userEmail": "user@example.com",
"credits": 13,
"background": 8,
"interactive": 5
}
],
"entries": [
{
"id": "1",
"userId": "0000000000000000000",
"userName": "Example User",
"userEmail": "user@example.com",
"action": "Company search",
"source": "interactive",
"credits": 1,
"subject": "Acme",
"createdAt": "2026-09-12 10:00:00"
}
],
"limit": 50,
"offset": 0
}
}Search
Company search
Search UK companies by name. A successful search uses 1 credit. The connector asks Companies House for the first 100 matches.
POST /ze-companies-house-assistant/search
Parameters
searchStringBody, required- Non-empty company name, or part of a name.
activeCompaniesOnlyBody- When true, Companies House is asked for active companies only.
Take company_number from an item and use it on the company routes. A missing key, an inactive subscription, or an upstream failure returns HTTP 500 with { "ERROR": "<message>" }.
payload = Map();
payload.put("searchString", "Acme Holdings");
payload.put("activeCompaniesOnly", false);
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/search";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 486,
"data": {
"total_results": 1,
"items": [
{
"company_number": "12345678",
"title": "ACME HOLDINGS LTD",
"company_status": "active",
"company_type": "ltd",
"date_of_creation": "2010-04-12",
"address": {
"address_line_1": "1 Example Street",
"locality": "London",
"postal_code": "EC1A 1AA"
}
}
]
}
}Advanced company search
Filtered company search. Credit cost is ceil(size / 100). Size 250 costs 3 credits. When size is omitted, the call costs 1 credit and size is not sent upstream.
POST /ze-companies-house-assistant/advanced-search
Parameters
company_name_includesBody- Text the company name must include.
company_name_excludesBody- Text the company name must not include.
company_statusBody- Companies House status, for example active.
company_typeBody- Companies House type, for example ltd.
sic_codesBody- Array of SIC code strings. The connector joins them with commas.
incorporated_fromBody- Incorporation date, YYYY-MM-DD.
incorporated_toBody- Incorporation date, YYYY-MM-DD.
dissolved_fromBody- Dissolution date, YYYY-MM-DD.
dissolved_toBody- Dissolution date, YYYY-MM-DD.
locationBody- Location text, for example London.
sizeBody- How many hits to request. The product UI uses 100–5000.
Send only the filters you need. Empty strings are dropped. An upstream 404 or 204 still uses the credits and returns items as an empty list with hits 0. Failures use the same HTTP 500 { "ERROR": "<message>" } shape as company search.
sicCodes = List();
sicCodes.add("62012");
payload = Map();
payload.put("company_name_includes", "Acme");
payload.put("company_status", "active");
payload.put("company_type", "ltd");
payload.put("sic_codes", sicCodes);
payload.put("incorporated_from", "2010-01-01");
payload.put("incorporated_to", "2024-12-31");
payload.put("location", "London");
payload.put("size", "100");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/advanced-search";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 486,
"data": {
"hits": 1,
"kind": "search#advanced-search",
"items": [
{
"company_number": "12345678",
"company_name": "ACME HOLDINGS LTD",
"company_status": "active",
"company_type": "ltd"
}
]
}
}Officer name search
Search officers across Companies House by name. A successful page uses 1 credit. The credit is taken after Companies House returns that page.
POST /ze-companies-house-assistant/officers/search
Parameters
searchStringBody, required- Non-empty person name.
itemsPerPageBody- Page size. Default 20, clamped to 1–100.
startIndexBody- Zero-based offset. Default 0, clamped to 0–10000.
Past the last page, Companies House HTTP 416 comes back as HTTP 200 with exhausted true and an empty items list, and no credit is used. The officer id for the appointments route is in links.officer.appointments.
payload = Map();
payload.put("searchString", "Smith");
payload.put("itemsPerPage", 20);
payload.put("startIndex", 0);
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/officers/search";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 486,
"data": {
"total_results": 1,
"items": [
{
"title": "Jane SMITH",
"address_snippet": "London",
"appointment_count": 2,
"description": "Total number of appointments 2",
"links": { "self": "/officers/abc123/appointments" }
}
]
}
}Company
Company profile
Company profile for one company number. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 486,
"data": {
"company_name": "ACME HOLDINGS LTD",
"company_number": "12345678",
"company_status": "active",
"type": "ltd",
"date_of_creation": "2010-04-12",
"jurisdiction": "england-wales",
"sic_codes": ["62012"],
"has_been_liquidated": false,
"has_charges": false,
"has_insolvency_history": false,
"registered_office_address": {
"address_line_1": "1 Example Street",
"locality": "London",
"postal_code": "EC1A 1AA"
},
"links": { "filing_history": "/company/12345678/filing-history" }
}
}Company officers
Officers appointed to one company. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}/officers
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
items_per_pageQuery- Page size. Officers and PSC accept 1–100. Filings and charges default to 100, clamped to 1–100.
start_indexQuery- Zero-based offset, from 0 to 100000.
register_viewQuery- true or false.
order_byQuery- appointed_on, resigned_on, or surname.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/officers?items_per_page=100";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"active_count": 1,
"resigned_count": 0,
"total_results": 1,
"start_index": 0,
"items_per_page": 100,
"items": [
{
"name": "SMITH, Jane",
"officer_role": "director",
"appointed_on": "2010-04-12",
"occupation": "Director",
"nationality": "British",
"country_of_residence": "England",
"links": { "officer": { "appointments": "/officers/abc123/appointments" } }
}
]
}
}Persons with significant control
Persons with significant control for one company. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}/persons-with-significant-control
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
items_per_pageQuery- Page size. Officers and PSC accept 1–100. Filings and charges default to 100, clamped to 1–100.
start_indexQuery- Zero-based offset, from 0 to 100000.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/persons-with-significant-control?items_per_page=100";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"active_count": 1,
"total_results": 1,
"items": [
{
"name": "Jane Smith",
"kind": "individual-person-with-significant-control",
"notified_on": "2016-04-06",
"natures_of_control": ["ownership-of-shares-75-to-100-percent"],
"nationality": "British",
"links": { "self": "/company/12345678/persons-with-significant-control/psc123" }
}
]
}
}Filing history
Filing history for one company. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}/filing-history
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
items_per_pageQuery- Default 100, clamped to 1–100.
start_indexQuery- Zero-based offset, from 0 to 100000.
categoryQuery- Comma-separated list. Allowed values: accounts, address, annual-return, capital, change-of-name, charges, confirmation-statement, incorporation, insolvency, liquidation, miscellaneous, mortgage, officers, persons-with-significant-control, resolution. Unknown values are dropped.
links.document_metadata on an item supplies the document id for the document download route.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/filing-history?items_per_page=100&category=accounts";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"total_count": 1,
"items": [
{
"transaction_id": "MzEyMzQ1Njc4",
"date": "2024-09-30",
"category": "accounts",
"type": "AA",
"description": "accounts-with-accounts-type-full",
"links": { "document_metadata": "/document/ABC123DEF" }
}
]
}
}Charges
Charges registered against one company. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}/charges
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
items_per_pageQuery- Default 100, clamped to 1–100.
start_indexQuery- Zero-based offset, from 0 to 100000.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/charges?items_per_page=100";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"total_count": 1,
"items": [
{
"charge_number": 1,
"status": "outstanding",
"classification": { "description": "A registered charge" },
"created_on": "2018-01-15",
"delivered_on": "2018-01-20",
"persons_entitled": [{ "name": "Example Bank Plc" }]
}
]
}
}Insolvency
Insolvency cases for one company. A successful call uses 1 credit.
GET /ze-companies-house-assistant/company/{companyNumber}/insolvency
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/insolvency";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"status": ["live-receiver-manager"],
"cases": [
{
"type": "receivership",
"number": "1",
"dates": [{ "type": "appointed-on", "date": "2020-05-01" }],
"practitioners": [{ "name": "Alex Example", "role": "receiver" }]
}
]
}
}Connected companies
Walk ownership above a company and list roles held. Each upstream Companies House call uses 1 credit, up to maxCalls.
GET /ze-companies-house-assistant/company/{companyNumber}/connected
Parameters
companyNumberPath- Exactly 8 characters, digits and uppercase letters: [0-9A-Z]. A lowercase number does not match this route.
maxDepthQuery- How many ownership levels to walk. Default 5, clamped to 1–8.
maxCallsQuery- Cap on upstream calls. Default 25, clamped to 1–40.
stoppedReason is null, call_cap, insufficient_credits, rate_limited, or upstream_error. If the first upstream call fails with HTTP 402 or 429, the request fails instead of returning a partial tree. creditsUsed is the number of upstream calls charged.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/company/12345678/connected?maxDepth=5&maxCalls=25";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 470,
"creditsUsed": 4,
"truncated": false,
"stoppedReason": null,
"data": {
"ownership": {
"companyNumber": "12345678",
"companyName": "ACME HOLDINGS LTD",
"companyStatus": "active",
"depth": 0,
"naturesOfControl": [],
"ceased": false,
"parents": []
},
"rolesHeld": [
{
"companyNumber": "87654321",
"companyName": "ACME TRADING LTD",
"companyStatus": "active",
"officerRole": "director",
"appointedOn": "2019-01-01",
"resignedOn": null
}
],
"notes": []
}
}People
Officer appointments
Appointments for one officer. A successful call uses 1 credit. Take officerId from an officer search or a company officer link.
GET /ze-companies-house-assistant/officers/{officerId}/appointments
Parameters
officerIdPath- Letters, digits, underscore, equals, or hyphen: [A-Za-z0-9_=-]+.
items_per_pageQuery- Default 50, clamped to 1–100.
start_indexQuery- Zero-based offset, from 0 to 100000.
register_viewQuery- true or false.
order_byQuery- appointed_on, resigned_on, or surname.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/officers/abc123/appointments?items_per_page=50";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"total_results": 1,
"items": [
{
"name": "Jane SMITH",
"officer_role": "director",
"appointed_on": "2010-04-12",
"appointed_to": {
"company_name": "ACME HOLDINGS LTD",
"company_number": "12345678",
"company_status": "active"
}
}
]
}
}PSC notifications
Companies notified of one person with significant control. A successful call uses 1 credit.
GET /ze-companies-house-assistant/persons-with-significant-control/{pscId}/notifications
Parameters
pscIdPath- Letters, digits, underscore, equals, or hyphen: [A-Za-z0-9_=-]+.
items_per_pageQuery- Default 25, clamped to 1–100.
start_indexQuery- Zero-based offset. Default 0.
filterQuery- Only active is forwarded to Companies House.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/persons-with-significant-control/psc123/notifications?items_per_page=25&filter=active";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"remainingCredits": 485,
"data": {
"total_results": 1,
"active_count": 1,
"ceased_count": 0,
"items_per_page": 25,
"start_index": 0,
"items": [
{
"name": "Jane Smith",
"kind": "individual-person-with-significant-control",
"notified_on": "2016-04-06",
"natures_of_control": ["ownership-of-shares-75-to-100-percent"],
"notified_to": {
"company_number": "12345678",
"company_name": "ACME HOLDINGS LTD",
"company_status": "active"
}
}
]
}
}Documents
Document download
Download one filing as a PDF. A successful download uses 1 credit. The body is the file, not JSON. Remaining credits are in the X-Remaining-Credits header.
GET /ze-companies-house-assistant/documents/{documentId}/content
Parameters
documentIdPath- Letters, digits, underscore, equals, or hyphen. Take it from filing-history links.document_metadata.
filenameQuery- Optional download name. Sanitised to a .pdf name, at most 180 characters. Default companies-house-{documentId}.pdf.
HTTP 400 means the id is invalid. HTTP 404 means the document was not found. HTTP 406 means it is not available as a PDF. HTTP 429 is a rate limit. HTTP 502 means the upstream body was not a file. Those errors use { "success": false, "ERROR": "<message>" }.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/documents/ABC123DEF/content?filename=accounts.pdf";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="accounts.pdf"
Cache-Control: private, no-store
X-Remaining-Credits: 486
<PDF bytes>CRM refresh
Refresh a company record
Refresh one Companies House Entry in Zoho CRM: profile, officers, persons with significant control, documents, and screenshots, according to the organisation’s settings. Each Companies House call inside the refresh uses 1 credit and is logged as a background refresh.
POST /ze-companies-house-assistant/refresh-company
Parameters
companyRecordIdBody, required- Record id of itlukcha__Companies_House_Entries.
The session user needs a connected Zoho OAuth token. companyNumber, officersUpdated, pscSaved, and documentsDownloaded are present when that step runs. warnings lists steps that were skipped.
Error codes: INVALID_PAYLOAD 400, COMPANIES_HOUSE_KEY_MISSING 400, INACTIVE_SUBSCRIPTION 402, INSUFFICIENT_CREDITS 402, ENTRY_NOT_FOUND 404, OAUTH_NOT_CONNECTED 409, COMPANY_NUMBER_MISSING 422, RATE_LIMIT 429, PROFILE_UNUSABLE 502, REFRESH_FAILED 500. Those bodies include success false, code, error, warnings, and nextUpdateSaved.
payload = Map();
payload.put("companyRecordId", "0000000000000000000");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/refresh-company";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"code": "SUCCESS",
"warnings": [],
"nextUpdateSaved": true,
"companyNumber": "12345678",
"officersUpdated": 3,
"pscSaved": true,
"documentsDownloaded": 1
}Refresh screenshots
Replace the company and officer screenshots on one Companies House Entry. This uses the saved Screenshotlayer key and does not call Companies House.
POST /ze-companies-house-assistant/refresh-screenshots
Parameters
companyRecordIdBody, required- Record id of itlukcha__Companies_House_Entries.
saved and deleted are attachment file names. When no screenshot is saved the status is HTTP 502 and code is SCREENSHOT_FAILED.
Other codes: INVALID_PAYLOAD 400, SCREENSHOT_KEY_MISSING 400, INACTIVE_SUBSCRIPTION 402, ENTRY_NOT_FOUND 404, OAUTH_NOT_CONNECTED 409, COMPANY_NUMBER_MISSING 422, SCREENSHOT_FAILED 500.
payload = Map();
payload.put("companyRecordId", "0000000000000000000");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/refresh-screenshots";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"code": "SUCCESS",
"companyName": "ACME HOLDINGS LTD",
"companyNumber": "12345678",
"replacedOld": true,
"saved": ["ACME-HOLDINGS-LTD-company-screengrab.webp"],
"deleted": [],
"warnings": []
}Settings
Read settings
Read organisation settings, including stored keys. This call does not use a credit and does not require an active subscription. Examples below use placeholders. A live response contains the stored values.
GET /ze-companies-house-assistant/settings
HTTP 401 means the session has no organisation. HTTP 404 means settings are not set up because there is no subscription row to create them from.
headers = Map();
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/settings";
response = invokeurl
[
url :requestUrl
type :GET
headers:headers
detailed:true
];
info response;{
"success": true,
"data": {
"updateIntervalDays": 30,
"accountsChangeName": false,
"accountsSetAddress": false,
"contactsSetAddress": false,
"leadsChangeName": false,
"leadsSetAddress": false,
"saveCompanyScreenshot": true,
"saveOfficersScreenshot": true,
"autoDeleteOldScreenshots": true,
"autoSavePsc": true,
"autoDownloadDocuments": false,
"documentCategories": ["accounts", "confirmation-statement"],
"documentDownloadRule": "most_recent",
"documentDownloadCount": 1,
"companiesHouseApiKey": "<stored-key>",
"screenshotlayerApiKey": "<stored-key>",
"fcaAuthEmail": "<stored-email>",
"fcaAuthKey": "<stored-key>",
"pendingOrgVariables": []
}
}Update settings
Patch any subset of the settings keys, except pendingOrgVariables. Unknown keys are ignored. The response is the full settings object.
PUT /ze-companies-house-assistant/settings
Parameters
updateIntervalDaysBody- Days between scheduled company refreshes. Default 30.
accountsChangeNameBody- Boolean. Update the Account name from Companies House.
accountsSetAddressBody- Boolean. Update the Account address.
contactsSetAddressBody- Boolean. Update Contact addresses.
leadsChangeNameBody- Boolean. Update the Lead name.
leadsSetAddressBody- Boolean. Update the Lead address.
saveCompanyScreenshotBody- Boolean.
saveOfficersScreenshotBody- Boolean.
autoDeleteOldScreenshotsBody- Boolean.
autoSavePscBody- Boolean. Store persons with significant control on the entry.
autoDownloadDocumentsBody- Boolean.
documentCategoriesBody- Array. Allowed values: accounts, confirmation-statement, officers, capital, charges, incorporation, resolution.
documentDownloadRuleBody- most_recent, last_n, or all.
documentDownloadCountBody- Used when the rule is last_n. Integer from 1 to 50.
companiesHouseApiKeyBody- Companies House REST API key. Shown here as a placeholder.
screenshotlayerApiKeyBody- Screenshotlayer access key. Shown here as a placeholder.
fcaAuthEmailBody- FCA email stored for the organisation.
fcaAuthKeyBody- FCA key stored for the organisation. Shown here as a placeholder.
An empty object, or a body with no recognised keys, returns HTTP 400 and "No settings were provided." A non-JSON body returns HTTP 400 and "Request body must be JSON."
payload = Map();
payload.put("updateIntervalDays", 30);
payload.put("autoSavePsc", true);
payload.put("documentDownloadRule", "most_recent");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/settings";
response = invokeurl
[
url :requestUrl
type :PUT
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"data": {
"updateIntervalDays": 30,
"accountsChangeName": false,
"accountsSetAddress": false,
"contactsSetAddress": false,
"leadsChangeName": false,
"leadsSetAddress": false,
"saveCompanyScreenshot": true,
"saveOfficersScreenshot": true,
"autoDeleteOldScreenshots": true,
"autoSavePsc": true,
"autoDownloadDocuments": false,
"documentCategories": ["accounts", "confirmation-statement"],
"documentDownloadRule": "most_recent",
"documentDownloadCount": 1,
"companiesHouseApiKey": "<stored-key>",
"screenshotlayerApiKey": "<stored-key>",
"fcaAuthEmail": "<stored-email>",
"fcaAuthKey": "<stored-key>",
"pendingOrgVariables": []
}
}Backfill settings
Copy organisation variables into settings columns that are still empty. A column that already has a value is left as it is.
POST /ze-companies-house-assistant/settings/backfill
Parameters
variablesBody- Map of Zoho organisation variable API names to string values, for example itlukcha__UK_Companies_House_API_Key.
HTTP 404 means there is no settings row. A non-JSON body returns HTTP 400.
variables = Map();
variables.put("itlukcha__UK_Companies_House_API_Key", "<companies-house-key>");
payload = Map();
payload.put("variables", variables);
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/settings/backfill";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"data": {
"updateIntervalDays": 30,
"accountsChangeName": false,
"accountsSetAddress": false,
"contactsSetAddress": false,
"leadsChangeName": false,
"leadsSetAddress": false,
"saveCompanyScreenshot": true,
"saveOfficersScreenshot": true,
"autoDeleteOldScreenshots": true,
"autoSavePsc": true,
"autoDownloadDocuments": false,
"documentCategories": ["accounts", "confirmation-statement"],
"documentDownloadRule": "most_recent",
"documentDownloadCount": 1,
"companiesHouseApiKey": "<stored-key>",
"screenshotlayerApiKey": "<stored-key>",
"fcaAuthEmail": "<stored-email>",
"fcaAuthKey": "<stored-key>",
"pendingOrgVariables": []
}
}Check the Companies House key
Test a Companies House API key and, when it is valid, save it for the organisation. Requires an active subscription.
POST /ze-companies-house-assistant/check-companies-house-api-key
Parameters
companiesHouseApiKeyBody, required- The key to test. The example uses a placeholder.
Failures return HTTP 500 and { "ERROR": "<message>" }. Messages include "Missing Companies House API Key", "Error testing Companies House API Key. Key is possibly invalid.", and "Subscription is not active".
payload = Map();
payload.put("companiesHouseApiKey", "<companies-house-key>");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/check-companies-house-api-key";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"message": "Companies House API Key is valid"
}Check the Screenshotlayer key
Test a Screenshotlayer access key and, when it is valid, save it for the organisation. Requires an active subscription. The body field name is screenlayerApiKey.
POST /ze-companies-house-assistant/check-screenshotlayer-api-key
Parameters
screenlayerApiKeyBody, required- The Screenshotlayer access key. The field name has no "shot".
Failures return HTTP 500 with both error and ERROR. Messages include "Missing Screenshotlayer API Key", "Invalid API Key.", "Secret Key Not Supported - Please Remove the Secret Key from your Screenshotlayer account and try again.", and "Rate Limit Exceeded - Please try again later."
payload = Map();
payload.put("screenlayerApiKey", "<screenshotlayer-key>");
headers = Map();
headers.put("Content-Type", "application/json");
headers.put("x-zep-session-id", sessionId);
requestUrl = "https://connector.zepartner.net/ze-companies-house-assistant/check-screenshotlayer-api-key";
response = invokeurl
[
url :requestUrl
type :POST
parameters:payload.toString()
headers:headers
detailed:true
];
info response;{
"success": true,
"data": "Screenshotlayer API Key is valid",
"message": "Screenshotlayer API Key is valid"
}What could work better in your business?
Tell Gregory where the friction is. You do not need to know the service or technology before getting in touch.
Work with Gregory Or email help@zepartner.net