> ## Documentation Index > Fetch the complete documentation index at: https://docs.godiligent.ai/llms.txt > Use this file to discover all available pages before exploring further. # Identify Company > Get company by various data points ## OpenAPI ````yaml GET /companies/identify openapi: 3.0.1 info: version: 1.5.0 title: Diligent description: > Download Postman collection [here](https://docs.godiligent.ai/files/postman_collection.json). servers: - url: https://api.godiligent.ai description: Production - url: https://api.sandbox.godiligent.ai description: Sandbox security: - xApiKey: [] tags: - name: CDD description: Customer Due Diligence - name: Company description: Company Information - name: Blocked Companies description: Manage blocked companies - name: Monitorings description: Website monitoring and alerts for changes and risks - name: Webhooks description: > ## How to Secure Webhook Deliveries To ensure that webhook payloads are securely transmitted and verified. This guide explains how to configure and validate webhook deliveries using a shared secret. ### How It Works When setting up a webhook, a secret is configured on both the sender (our system) and the receiver (your endpoint). Each webhook payload is signed using this secret, allowing the receiver to verify its authenticity. #### Step 1: Configuring Your Webhook Secret 1. When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomly generated string. 2. Store this secret securely on your server; it should never be exposed publicly. #### Step 2: Receiving Webhook Payloads When your server receives a webhook event, the request will include an `X-Signature` header containing a HMAC signature of the payload. Example header: ``` X-Signature: sha256=abcdef1234567890... ``` #### Step 3: Validating the Webhook Signature To verify the webhook payload: 1. Retrieve the `X-Signature` value from the request headers. 2. Compute the HMAC SHA-256 signature of the request payload using your webhook secret. 3. Compare the computed signature with the one in the `X-Signature` header. 4. If they match, the webhook is valid. #### (Python) ```python import hashlib import hmac import json def verify_webhook_signature(secret, payload, signature): computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() expected_signature = f"sha256={computed_signature}" return hmac.compare_digest(expected_signature, signature) # Example usage: secret = "your_webhook_secret" payload = json.dumps({"event": "example"}) received_signature = "sha256=abcdef1234567890..." if verify_webhook_signature(secret, payload, received_signature): print("Valid webhook received!") else: print("Invalid webhook signature!") ``` #### (JavaScript) ```javascript const crypto = require('crypto'); function verifyWebhookSignature (secret, payload, signature) { const computedSignature = `sha256=${crypto.createHmac('sha256', secret) .update(payload) .digest('hex')}`; return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature)); } // Example usage: const secret = "your_webhook_secret"; const payload = JSON.stringify({ event: "example" }); const receivedSignature = "sha256=abcdef1234567890..."; if (verifyWebhookSignature(secret, payload, receivedSignature)) { console.log("Valid webhook received!"); } else { console.log("Invalid webhook signature!"); } ``` #### Security Considerations - Always use HTTPS to prevent interception of webhook payloads. - Reject webhook requests that fail signature validation. - Rotate secrets periodically to enhance security. By following this guide, you ensure that webhook deliveries are secure and trusted. - name: Instant Screening (experimental) description: Instant Website Screening API - name: Name Screening description: Name screening search, alert management and remediation paths: /companies/identify: get: tags: - Company summary: identify description: identify company by various data points parameters: - name: legal_name in: query description: The legal_name of the company required: false schema: type: string example: CrossLend GmbH - name: address in: query description: The address of the business, partial or full address required: false schema: type: string example: CrossLend GmbH - name: vat_number in: query description: The VAT number of the business required: false schema: type: string example: DE123456789 - name: registry_profile in: query description: The level of details to be returned required: false schema: type: string enum: - FULL - BASIC example: FULL - name: country_code in: query description: >- The country code of the business, in alpha-2 format (ISO 3166-1 alpha-2) required: false schema: type: string example: DE - name: register_number in: query description: >- The company registration number (e.g. Companies House number for UK, SIRET for FR, P.IVA or REA code for IT). Must be combined with `country_code`. required: false schema: type: string example: '12345678' - name: registry_infocamere_enabled in: query description: >- When `true`, enables the Infocamere registry source for Italian companies. Only relevant when identifying Italian companies via `register_number` or `vat_number`. required: false schema: type: boolean default: false example: true - name: validate_address in: query description: >- When `true`, validates and normalises the returned address against a reference dataset. required: false schema: type: boolean default: false example: false responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Registry' '400': description: Bad Request content: application/json: schema: type: array items: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized '403': description: Forbidden '404': description: Not found '500': description: Internal Server Error security: - xApiKey: [] components: schemas: Registry: type: object required: - name - legal_form - register - address - ownership - source properties: status: type: string example: ACTIVE enum: - ACTIVE - REGISTERED - INACTIVE - SUSPENDED - IN_REGISTRATION - TERMINATED name: type: string example: XYZZ GmbH commercial_name: type: string is_blocked: type: boolean default: false legal_form: type: string example: GmbH description: type: string example: SOFTWARE CONSULTANCY register: type: object required: - id - country properties: id: type: string example: HRB 259538 B country: type: string example: DE city: type: string example: Charlottenburg (Berlin) foundation_date: type: string example: '2023-12-04' address: $ref: '#/components/schemas/Address' vat_number: type: string representation_rules: type: string example: This is a placeholder for representation rules. signatory_powers: type: array items: $ref: '#/components/schemas/SignatoryPower' ownership: type: object properties: shareholders: type: array items: $ref: '#/components/schemas/Shareholder' total_percentage: type: integer example: 100 total_shareholders_count: type: integer example: 1 total_major_shareholders_count: type: integer example: 1 total_ubos_count: type: integer example: 1 industry_classifications: type: object properties: ateco: type: array items: type: string example: '47199' nace: type: array items: type: string example: '4719' sic: type: array items: type: string example: '5999' pec: type: string example: QUADERNOAQUADRETTISRL@ARUBAPEC.IT rea_code: type: string example: '128207' financials: type: object properties: date: type: string example: '2022-12-31' items: type: array items: type: object properties: id: type: string example: share_capital enum: - turnover - share_capital - net_worth note: type: string description: The note of the financial item unit: type: string example: EUR value: type: number format: int64 example: 100000 extras: type: array items: type: object properties: name: type: string example: website value: type: string example: www.example.eu source: $ref: '#/components/schemas/Source' ValidationError: type: object properties: errors: type: array items: $ref: '#/components/schemas/ValidationErrorItem' required: - errors Address: type: object properties: formatted_address: type: string example: 123 Imaginary St, 45678 Fictional City components: type: object properties: street: type: string example: Imaginary St street_number: type: string example: '123' state: type: string example: IS locality_code: type: string example: IS city: type: string example: Fictional City postal_code: type: string example: '45678' country_code: type: string example: FC country: type: string example: Fictionland type: type: string enum: - residential - business - unknown example: residential is_valid: type: boolean example: true is_verified: type: boolean example: true is_suspicious: type: boolean example: false is_blacklisted: type: boolean example: false is_primary: type: boolean example: true street_view: type: string sources: type: array items: $ref: '#/components/schemas/Source' SignatoryPower: type: object properties: first_name: type: string example: John last_name: type: string example: Doe date_of_birth: type: string example: '1990-01-01' entity_name: type: string example: Example GmbH location: type: string example: City, Country role: type: string example: ROLE effective_date: type: string example: '2024-01-01' representation: type: string example: Representation details role_local: type: string example: Role signatory_power: type: string example: POWER_TYPE Shareholder: type: object properties: name: type: string example: John Doe percentage: type: integer example: 100 type: type: string example: INDIVIDUAL location: type: string example: City, Country is_major_shareholder: type: boolean example: true is_ubo: type: boolean example: true gender: type: string example: MALE tax_code: type: string example: '123456789' address: type: string example: 123 Main St, City, Country Source: required: - name type: object properties: name: type: string example: Source Name link: type: string example: https://www.example.com ValidationErrorItem: type: object properties: path: type: array items: type: string description: JSON path to the field with the error message: type: string description: Error message code: type: string description: Error code indicating the type of error required: - path - message - code securitySchemes: xApiKey: type: apiKey name: X-API-KEY in: header ````