API Reference

Lookup prospects by provider ID

Returns the provider-id lookup result plus any company name and title metadata Sonarly has already stored for the matched prospect.

GET/v1/accounts/{accountGroupId}/prospects/by-provider-id/{providerId}

Scoped lookup

Provider-id lookup only returns prospect matches in the requested account group and never guesses between duplicate matches.

Integration notes

Permissions

prospecting:read for source and job reads, prospects:read for provider-id lookup, and prospecting:write for starting or cancelling jobs.

Async

POST /prospecting returns 202 Accepted with a job id. Poll GET /prospecting/{jobId} and cancel with POST /prospecting/{jobId}/cancel when needed.

Parameters

accountGroupIdPath

Type: string

Account group ID that scopes the request.

Required

providerIdPath

Type: string

External provider ID used to map the source record to Sonarly.

Required

Request body

This endpoint does not define a request body.

Responses

200

Provider ID prospect lookup result with identity, company, and title metadata

Schema: ProviderIdProspectLookupSuccessResponse

401

Invalid or missing API key

Schema: ErrorResponse

403

Missing required permission

Schema: ErrorResponse

422

Request validation failed

Schema: ValidationErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

Response examples

200 Example JSONProviderIdProspectLookupSuccessResponse

{
    "success": true,
    "data": {
        "providerId": "507f1f77bcf86cd799439011",
        "resolution": "none",
        "matches": [
            {
                "prospectId": "507f1f77bcf86cd799439011",
                "personId": "507f1f77bcf86cd799439011",
                "publicIdentifier": "string",
                "linkedinUrl": "https://example.com/resource",
                "name": "Avery Stone",
                "companyName": "Avery Stone",
                "title": "string"
            }
        ]
    },
    "error": null,
    "traceId": "507f1f77bcf86cd799439011"
}

401 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

403 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

422 Example JSONValidationErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

429 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

500 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}