# Data enrichment Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md ## POST /enrichment/search/persons **Search for people** `operationId: DataEnrichmentController_searchPersons` Searches provider data for people matching criteria. Each search calls an external provider and typically consumes credit with them. #### Signature ```http POST /enrichment/search/persons (body) -> Matching people ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Calls a paid third-party provider. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/person` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body Search criteria. ```json { "name": "Ada Lovelace", "company": "Acme" } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | Matching people | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/search/companies **Search for companies** `operationId: DataEnrichmentController_searchCompanies` Searches provider data for companies matching criteria. #### Signature ```http POST /enrichment/search/companies (body) -> Matching companies ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Calls a paid third-party provider. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/company` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body Search criteria. ```json { "name": "Acme", "domain": "acme.example" } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | Matching companies | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/person **Enrich a person** `operationId: DataEnrichmentController_enrichPerson` Looks up additional data for one person from an identifier — usually an email address. The data comes from a third party and can be stale or wrong; treat it as a hint, not a fact about a real individual. #### Signature ```http POST /enrichment/person (body) -> The enriched profile ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Third-party data — accuracy is not guaranteed. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/bulk` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body Who to enrich. ```json { "email": "ada@example.com" } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | The enriched profile | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/company **Enrich a company** `operationId: DataEnrichmentController_enrichCompany` Looks up additional data for a company, usually from its domain. #### Signature ```http POST /enrichment/company (body) -> The enriched company ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Third-party data. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/person` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body Which company. ```json { "domain": "acme.example" } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | The enriched company | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/validate-email **Validate an email address** `operationId: DataEnrichmentController_validateEmail` Checks an address for deliverability through the provider. Worth running before adding an address to a send list — invalid addresses cause bounces, which damage sender reputation. #### Signature ```http POST /enrichment/validate-email (body) -> Validation result ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `GET /broadcast/validate/email/{email}` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body The address. ```json { "email": "ada@example.com" } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | Validation result | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/bulk **Bulk enrich** `operationId: DataEnrichmentController_bulkEnrich` Enriches many records in one call. Each record is a provider lookup, so cost and duration scale with the list — check the provider's credit before submitting a large batch. #### Signature ```http POST /enrichment/bulk (body) -> Per-record results ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Cost scales with the batch size. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/person` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Request body The records to enrich. ```json { "type": "person", "items": [ { "email": "ada@example.com" }, { "email": "grace@example.com" } ] } ``` ### Responses | Status | Meaning | | --- | --- | | `201` | Per-record results | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## GET /enrichment/providers **List enrichment providers** `operationId: DataEnrichmentController_getProviders` The third-party data providers available for enrichment. #### Signature ```http GET /enrichment/providers () -> Providers ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `GET /enrichment/providers/{name}/status` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Responses | Status | Meaning | | --- | --- | | `200` | Providers | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## GET /enrichment/providers/{name}/status **Get a provider's status** `operationId: DataEnrichmentController_getProviderStatus` Whether a provider is reachable and configured — the check when enrichment starts returning nothing. #### Signature ```http GET /enrichment/providers/{name}/status (name: string) -> Provider status ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `GET /enrichment/providers` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `name` | path | string | yes | Provider name. | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Responses | Status | Meaning | | --- | --- | | `200` | Provider status | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. | ## POST /enrichment/cache/clear **Clear the enrichment cache** `operationId: DataEnrichmentController_clearCache` Drops cached provider responses. The next lookups go back to the provider and are charged again — clear it when data is known stale, not as routine housekeeping. #### Signature ```http POST /enrichment/cache/clear () -> The result ``` #### Access Requires a bearer JWT (`Authorization: Bearer `). #### Notes - Subsequent lookups are re-charged. #### Errors Plus the standard platform errors: `401`, `403`, `429`, `500`. #### See also - `POST /enrichment/person` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. | ### Responses | Status | Meaning | | --- | --- | | `201` | The result | | `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. | | `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. | | `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. | | `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |