API Endpoints | Netra RIA Cloud Docs

Netra API provides a powerful set of endpoints for managing and interacting with entities within your Netra environment. All API endpoints are prefixed with /api/v1 and require API Key Authentication.

Authentication

All requests to the Netra API must be authenticated with a valid API Key. Include your API Key in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Base URL

The base URL for all Netra API endpoints is:

https://api.netra.technology/v1

Entities

The /entities endpoint allows you to programmatically manage your organizations and persons.

Get All Entities

GET /v1/entities

Retrieves a list of all entities (organizations and persons) associated with your team.

Request

GET /v1/entities
Authorization: Bearer YOUR_API_KEY

Response (200 OK)

json

[
  {
    "id": "clw6f1o00000008j7e5m4d0t2",
    "name": "Example Corp",
    "type": "organization",
    "caseStatus": "NOT_STARTED",
    "registration": "-",
    "countryCode": "US",
    "riskLevel": "Low Risk",
    "riskScore": 20,
    "netraId": "d41beac5bc0a4f209da0ddd4f7312ef5",
    "lastUpdate": "Jul 19, 2025",
    "dueDate": "-",
    "createdAt": "2025-07-19T10:00:00.000Z",
    "updatedAt": "2025-07-19T10:00:00.000Z"
  },
  {
    "id": "clw6f1o00000108j7e5m4d0t3",
    "name": "Jane Doe",
    "type": "person",
    "caseStatus": "IN_PROGRESS",
    "registration": "GB",
    "countryCode": "GB",
    "riskLevel": "Medium Risk",
    "riskScore": 60,
    "netraId": "d41beac5bc0a4f209da0ddd4f7312ef5",
    "lastUpdate": "Jul 18, 2025",
    "dueDate": "-",
    "createdAt": "2025-07-18T09:00:00.000Z",
    "updatedAt": "2025-07-18T09:00:00.000Z"
  }
]

Create Entity

POST /v1/entities

Creates a new organization or person entity in your Netra environment. This will trigger Netra's automated screening and enrichment processes.

Request

POST /v1/entities
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "[String]",
  "type": "[String]",  // "organization" or "person"
  "countryCode": "[String, 2-letter ISO country code]",
  "registration": "[String]",
  "birthDate": "[String]",
  "nationalId": "[String]"
}

Request Body Fields

Field	Type	Required	Description
`name`	`string`	Yes	The full name of the organization (including legal form, e.g., "Example Corp GmbH") or person.
`type`	`string`	Yes	The type of entity. Must be `"organization"` or `"person"`.
`countryCode`	`string`	No	2-letter ISO country code (e.g., "US", "GB").
`registration`	`string`	No	Registration number/ID for organizations.
`birthDate`	`string`	No	Date of birth for persons (format: YYYY-MM-DD).
`nationalId`	`string`	No	National ID number for persons.

Example Request (Organization)

bash

curl -X POST https://api.netra.technology/v1/entities \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Example Corp",
  "type": "organization",
  "countryCode": "US",
  "registration": "-"
}'

Example Request (Person)

bash

curl -X POST https://api.netra.technology/v1/entities \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Jane Doe",
  "type": "person",
  "countryCode": "GB",
  "birthDate": "1990-05-15",
  "nationalId": "987654321"
}'

Response (201 OK)

Returns the created entity object.

json

{
  "success": true,
  "data": {
    "id": "clw6g1p00000008j7e5m4d0t2",
    "name": "Example Corp",
    "countryCode": "US",
    "caseStatus": "NOT_STARTED",
    "netraId": "d41beac5bc0a4f209da0ddd4f7312ef5",
    "tags": [],
    "createdAt": "2025-07-19T11:00:00.000Z",
    "updatedAt": "2025-07-19T11:00:00.000Z",
    "teamId": "your_team_id"
  }
}

Get Entity Network

GET /v1/entities/{id}/network

Retrieves the full network graph for a specific entity, including all associated nodes (persons and organizations), their relationships, and detailed risk information. This is the same data that powers the Agent view in the Netra application.

Request

GET /v1/entities/{id}/network
Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the root entity.

Response (200 OK)

The response contains a data object with nodes and relations.

nodes: An object where each key is a node ID and the value is an object containing the node's details.
relations: An array of objects, each describing a relationship between two nodes.

json

{
  "success": true,
  "data": {
    "nodes": {
      "clw6f1o00000008j7e5m4d0t2": {
        "id": "clw6f1o00000008j7e5m4d0t2",
        "name": "Example Corp",
        "full_name": "Example Corporation",
        "type": "organization",
        "country_code": "US",
        "pep_json": "[]",
        "sanctions_json": "[]",
        "adverse_media_json": "[]",
        "calculatedRiskScore": 5
      },
      "clw6f1o00000108j7e5m4d0t3": {
        "id": "clw6f1o00000108j7e5m4d0t3",
        "name": "Jane Doe",
        "full_name": "Jane Doe",
        "type": "person",
        "country_code": "GB",
        "pep_json": "[{\"name\":\"Jane Doe\", \"position\":\"Director\", \"sources\":[\"source_a\"]}]",
        "sanctions_json": "[]",
        "adverse_media_json": "[]",
        "calculatedRiskScore": 15
      }
    },
    "relations": [
      {
        "source": "clw6f1o00000108j7e5m4d0t3",
        "target": "clw6f1o00000008j7e5m4d0t2",
        "type": "HasRole",
        "label": "Director",
        "risk": 10,
        "details": {
          "sources": ["corp_registry_x"]
        }
      }
    ]
  }
}

Node Object Fields

The nodes object in the response may contain the following fields for each node. Some fields may be optional or only present for certain entity types.

Field	Type	Description	Notes / Aliases
`name`	string	Name of the entity
`full_name`	string	Full legal name of the entity
`country_code`	string	2-letter ISO country code (e.g., `US`, `GB`, `IQ`)	`country` may be used
`pep`	array	Array of PEP (Politically Exposed Person) data objects
`sanctions`	array	Array of sanctions data objects
`adverse_media`	array	Array of adverse media data objects
`calculatedRiskScore`	number	Calculated risk score for the entity
`sources`	array	Data sources for the entity	Optional
`registration_number`	string	Registration number (for organizations)	Optional
`industry`	array	List of industries	Optional
`alternative_names`	array	Alternative names for the entity	Optional
`branch_offices`	array	List of branch offices	Optional
`risks`	array	List of risk factors	Optional
`size`	string	Size of the entity (e.g., `Small`, `Medium`, `Large`)	Optional
`industry_classification_codes`	array	Array of industry classification codes (e.g., NAICS, SIC)	Optional
`node_type`	string	Node type (e.g., `Entity`, `Person`)	Optional
`birth_date`	string	Date of birth for persons (format: YYYY-MM-DD)	Optional, for persons only

Note: Not all fields are present for every node. Field names may vary depending on the data source or API version. Always check the actual API response for the most accurate structure.

Relation Object Fields

The relations array in the response contains objects describing relationships between nodes. Each relation object has the following structure:

Field	Type	Description
`type`	string	The type of relationship. Possible values: `ShareholdingRelationship`, `VotingRightsRelationship`, `SubsidiaryRelationship`, `RoleRelationship`, `PartnershipRelationship`, `InvestmentRelationship`, `SupplierRelationship`, `ControlsRelationship`, `AcquisitionRelationship`, `BranchRelationship`
`details`	object	An object containing details about the relationship. May include:
		- `uid` (string): Unique identifier for the relationship
		- `is_executive` (boolean, for roles): Whether the role is executive
		- `description` (string): Description of the relationship
		- `key_position` (string, for roles): Key position title
		- `role_type` (string, for roles): Type of role (e.g., `advisor`, `board_member`, `executive`)
		- `sources` (array): Array of source URLs
		- `exact_share` (float, for shareholding): The exact share as a float (e.g., 0.005)
`source`	string	The node ID of the source entity in the relationship
`target`	string	The node ID of the target entity in the relationship

Note: All fields that previously ended with _json (such as pep_json, sanctions_json, adverse_media_json) are now returned as arrays, not JSON strings.

Search Organizations

POST /api/search/organizations

Searches for organizations on the web using external data sources. This endpoint uses AI-powered search to find organization profiles based on company name, registration number, country, and industry.

Request

bash

POST /api/search/organizations
Content-Type: application/json

{
  "company_name": "[String]",
  "company_registration_number": "[String]",
  "countryCode": "[String]",
  "industry": "[String]"
}

Request Body Fields

Field	Type	Required	Description
`company_name`	`string`	Yes	The name of the organization to search for.
`company_registration_number`	`string`	No	The registration number of the organization.
`countryCode`	`string`	No	The country where the organization is located (e.g., "Germany", "United States").
`industry`	`string`	No	The industry sector of the organization.

Example Request

bash

curl -X POST https://api.netra.technology/api/search/organizations \
-H "Content-Type: application/json" \
-d '{
  "company_name": "Example Corp",
  "company_registration_number": "-",
  "countryCode": "US",
  "industry": ""
}'

Response (200 OK)

Returns an array of organization profiles found on the web.

json

{
  "results": [
    {
      "company_name": "Example Corp",
      "company_registration_number": "-",
      "country": "United States",
      "country_code": "US",
      "industry": "",
      "website_url": "",
      "source_url": ""
    }
  ]
}

Response Fields

Field	Type	Description
`company_name`	`string`	The full name of the organization.
`company_registration_number`	`string`	The registration number of the organization.
`country`	`string`	The country where the organization is located.
`country_code`	`string`	The ISO 2-digit country code (e.g., "DE", "US").
`industry`	`string`	The industry sector of the organization.
`website_url`	`string`	The organization's website URL.
`source_url`	`string`	The source URL where this information was found.

Search Persons

POST /api/search/persons

Searches for persons on the web using external data sources. This endpoint uses AI-powered search to find real person profiles based on name, birth date, country, nationality, and national ID number.

Request

bash

POST /api/search/persons
Content-Type: application/json

{
  "first_name": "[String]",
  "last_name": "[String]",
  "name": "[String]",
  "full_name": "[String]",
  "birth_date": "[String]",
  "countryCode": "[String]",
  "nationality": "[String]",
  "national_id_number": "[String]"
}

Request Body Fields

Field	Type	Required	Description
`first_name`	`string`	No*	The first name of the person.
`last_name`	`string`	No*	The last name of the person.
`name`	`string`	No*	The full name of the person (legacy field).
`full_name`	`string`	No*	The full name of the person (preferred field).
`birth_date`	`string`	No	The person's date of birth (various formats supported).
`countryCode`	`string`	No	The country where the person is located (e.g., "Germany", "United States").
`nationality`	`string`	No	The person's nationality.
`national_id_number`	`string`	No	The person's national identification number or passport number.

*At least one name field is required: first_name + last_name, name, or full_name.

Example Request

bash

curl -X POST https://api.netra.technology/api/search/persons \
-H "Content-Type: application/json" \
-d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "birth_date": "1990-05-15",
  "countryCode": "GB",
  "nationality": "British",
  "national_id_number": "987654321"
}'

Alternative Example Request (using full_name)

bash

curl -X POST https://api.netra.technology/api/search/persons \
-H "Content-Type: application/json" \
-d '{
  "full_name": "Jane Doe",
  "birth_date": "1990-05-15",
  "countryCode": "GB"
}'

Response (200 OK)

Returns an array of person profiles found on the web.

json

{
  "results": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "birth_date": "1990-05-15",
      "country": "United Kingdom",
      "country_code": "GB",
      "nationality": "British",
      "national_id_number": "987654321",
      "profile_image_url": "",
      "source_url": ""
    }
  ]
}

Response Fields

Field	Type	Description
`first_name`	`string`	The person's first name.
`last_name`	`string`	The person's last name.
`birth_date`	`string`	The person's date of birth.
`country`	`string`	The country where the person is located.
`country_code`	`string`	The ISO 2-digit country code (e.g., "DE", "US").
`nationality`	`string`	The person's nationality.
`national_id_number`	`string`	The person's national identification number.
`profile_image_url`	`string`	The person's profile image URL (currently empty as image support is not implemented).
`source_url`	`string`	The source URL where this information was found.

Bulk Create Entities

POST /v1/entities/bulk

Creates multiple entities (organizations and persons) in a single request. This is more efficient for importing large amounts of data than making individual POST requests for each entity. You can upload up to 1,000 entities per request.

Request

POST /v1/entities/bulk
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "entities": [
    {
      "name": "Example Corp",
      "type": "organization",
      "countryCode": "US",
      "registration": "-",
      "tags": "customer,important"
    },
    {
      "name": "Jane Doe",
      "type": "person",
      "countryCode": "GB",
      "first_name": "Jane",
      "last_name": "Doe",
      "birth_date": "1990-05-15"
    }
  ]
}

Request Body Fields

The request body must contain an entities array, where each object represents an entity to be created.

Field	Type	Required	Description
`name`	`string`	Yes	The full name of the organization (including legal form, e.g., "Example Corp GmbH") or person. For persons, `first_name` and `last_name` are preferred.
`type`	`string`	Yes	The type of entity. Must be `"organization"` or `"person"`.
`countryCode`	`string`	Yes	2-letter ISO country code (e.g., "US", "GB").
`registration`	`string`	No	Registration number for an organization.
`tags`	`string`	No	A comma-separated string of tags.
`first_name`	`string`	For Persons	The first name of the person.
`last_name`	`string`	For Persons	The last name of the person.
`birth_date`	`string`	No	The person's date of birth in `YYYY-MM-DD` format.
`nationality`	`string`	No	The person's nationality as a 2-letter ISO country code.
`national_id`	`string`	No	The person's national identification number.

Response (201 OK)

Returns a summary of the bulk operation, including the number of successful creations and a list of any errors that occurred.

json

{
  "success": true,
  "data": {
    "successCount": 2,
    "errorCount": 1,
    "errors": [
      "Row 3: Organization 'Already Exists Corp' already exists in your team."
    ]
  }
}

Add Document to Entity

POST /v1/entities/{id}/documents

Associates a new document with a specific entity by providing a URL to the document. This action triggers Netra's automated document analysis processes. The document at the provided URL must be publicly accessible for processing.

Request

POST /v1/entities/{id}/documents
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the root entity.

Request Body Fields

Field	Type	Required	Description
`document_url`	`string`	Yes	The publicly accessible URL of the document to be processed.
`title`	`string`	No	A title for the document. If not provided, the filename from the URL is used.
`type`	`string`	No	The type of document. Defaults to `other`. Possible values: `identity_document`, `financial_statement`, `certificate`, `contract`, `ubo_declaration`, `business_license`, `risk_assessment`, `other`.

Example Request

bash

curl -X POST https://api.netra.technology/v1/entities/clw6f1o00000008j7e5m4d0t2/documents \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "document_url": "https://example.com/path/to/ubo_declaration.pdf",
  "type": "ubo_declaration",
  "title": "UBO Declaration 2025"
}'

Response (200 OK)

Returns an object confirming the document processing has started, including the id of the created document record and a run_id for tracking the analysis process.

json

{
  "success": true,
  "data": {
    "documentId": "clx5e8f0a000108jlc8s1a2b3",
    "message": "Document processing successfully triggered",
    "run_id": "run_98765fedcba"
  }
}

Rescan Entity

PUT /v1/entities/{id}

Initiates a rescan of an existing entity. This action resets the case status to "Not Started" and triggers Netra's automated screening and enrichment processes again. This is useful when new information has been added to an entity (e.g., a new document) or if you want to re-evaluate the entity against the latest data sources.

Request

PUT /v1/entities/{id}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "action": "rescan"
}

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the entity.

Request Body Fields

Field	Type	Required	Description
`action`	`string`	Yes	The action to perform. Must be set to `"rescan"`.

Example Request

bash

curl -X PUT https://api.netra.technology/v1/entities/clw6f1o00000008j7e5m4d0t2 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "action": "rescan"
}'

Response (200 OK)

Returns the updated entity object with the reset caseStatus and new timestamps.

json

{
  "success": true,
  "data": {
    "id": "clw6f1o00000008j7e5m4d0t2",
    "name": "Example Corp",
    "type": "organization",
    "caseStatus": "NOT_STARTED",
    "registration": "-",
    "countryCode": "US",
    "riskLevel": "Low Risk",
    "riskScore": 20,
    "netraId": "d41beac5bc0a4f209da0ddd4f7312ef5",
    "lastUpdate": "Jul 20, 2025",
    "dueDate": "-",
    "createdAt": "2025-07-20T12:00:00.000Z",
    "updatedAt": "2025-07-20T12:00:00.000Z"
  }
}

Error Handling

All API endpoints return standard HTTP status codes for errors. The response body will contain a success: false field and an error message.

json

{
  "statusCode": 401,
  "success": false,
  "error": "Unauthorized"
}

Common error codes include:

401 Unauthorized: Missing or invalid API key.
400 Bad Request: Invalid input or missing required fields.
403 Forbidden: Entity limit reached for your team, or other permission issues.
404 Not Found: The requested resource does not exist.
500 Internal Server Error: An unexpected server-side error occurred. Contact support if this persists.

Authentication #

Base URL #

Entities #

Get All Entities #

Request #

Response (200 OK) #

Create Entity #

Request #

Request Body Fields #

Example Request (Organization) #

Example Request (Person) #

Response (201 OK) #

Get Entity Network #

Request #

Path Parameters #

Response (200 OK) #

Node Object Fields #

Relation Object Fields #

Search Organizations #

Request #

Request Body Fields #

Example Request #

Response (200 OK) #

Response Fields #

Search Persons #

Request #

Request Body Fields #

Example Request #

Alternative Example Request (using full_name) #

Response (200 OK) #

Response Fields #

Bulk Create Entities #

Request #

Request Body Fields #

Response (201 OK) #

Add Document to Entity #

Request #

Path Parameters #

Request Body Fields #

Example Request #

Response (200 OK) #

Rescan Entity #

Request #

Path Parameters #

Request Body Fields #

Example Request #

Response (200 OK) #

Error Handling #

Authentication

Base URL

Entities

Get All Entities

Request

Response (200 OK)

Create Entity

Request

Request Body Fields

Example Request (Organization)

Example Request (Person)

Response (201 OK)

Get Entity Network

Request

Path Parameters

Response (200 OK)

Node Object Fields

Relation Object Fields

Search Organizations

Request

Request Body Fields

Example Request

Response (200 OK)

Response Fields

Search Persons

Request

Request Body Fields

Example Request

Alternative Example Request (using full_name)

Response (200 OK)

Response Fields

Bulk Create Entities

Request

Request Body Fields

Response (201 OK)

Add Document to Entity

Request

Path Parameters

Request Body Fields

Example Request

Response (200 OK)

Rescan Entity

Request

Path Parameters

Request Body Fields

Example Request

Response (200 OK)

Error Handling