> ## Documentation Index > Fetch the complete documentation index at: https://developers.activeprospect.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Ping Data > Retrieve ping data directly from a Certificate. When a lead vendor only provides a TrustedForm Certificate URL, Ping data can be retrieved directly without a Ping URL. Simply append `/ping` to the Certificate URL and perform an authenticated `GET`. A certificate's Ping data can be accessed two ways: - Querying a modified TrustedForm Certificate URL - Querying a vendor-provided TrustedForm Ping URL ## OpenAPI ````yaml /api-reference/trustedform_v2.yaml get /{cert_id}/ping openapi: 3.0.0 info: version: 2.0.0 title: TrustedForm Claiming API termsOfService: https://activeprospect.com/trustedform-eula description: > # Overview TrustedForm account holders who are receiving certified leads should use our API to claim the certificate provided with each lead. Doing so verifies the legitimacy of the certificate, stores the certificate for future reference, and provides programmatic access to the information shown on the certificate. To claim a certificate, send an HTTP POST request to the certificate URL sent by your publisher. * Do not make a request unless the URL starts with `https://cert.trustedform.com`, otherwise you may expose your TrustedForm credentials to someone else * Use a POST request — any other type of request will not claim the certificate * Use the `Accept: application/json` request header * Use the `Content-Type: application/json` or `Content-Type: application/x-www-form-urlencoded` header, and encode the request body accordingly * Use the API key provided on the "Settings" tab in the [TrustedForm Application](https://app.trustedform.com/#account) and the username 'API' ## Reference When you claim a certificate, you can pass the optional `reference` parameter. We will store this value along with your claimed certificate. The general idea is that you can pass your lead identifier which will provide a back-reference to the certified lead that you received. This will allow you to know which lead a certificate belongs to, just by examining the certificate data. In the case that your publisher has passed you a two leads with the same Certificate URL, this reference parameter will allow you to determine which lead it was originally passed with. If you are a LeadConduit customer, the LeadConduit Lead URL will be automatically sent as the reference. This allows you to refer back to the lead with which an individual certificate was collected. ## Vendor When claiming a certificate, you can pass the optional `vendor` parameter. We will store this value along with your claimed certificate. Later when you use TrustedForm reporting, you can easily filter or group by vendor. If you use our LeadConduit platform, the vendor will be automatically sent with each certificate claim request. ## Campaign ID When claiming a certificate, you can pass the optional `campaign_id` parameter. It's an optional identifier for the campaign associated with the lead. Use this to track which campaign generated the lead without relying on the vendor field. TrustedForm will record this value on the certificate stored in your account and include it in reporting. ## Fingerprints When you claim a certificate you can calculate lead fingerprint values using the email and phone number you received in the lead data accompanying the certificate. Each fingerprint value is a SHA1 hash of a email or phone value. Each fingerprint value should be provided in a `fingerprint` parameter. If at least one of the fingerprints you provide does not match one of those collected on the certificate you will receive the `none of the provided fingerprints match` in the claim `warnings` field. This indicates that the lead data collected on the form does not match the lead data that you received. If you use our LeadConduit platform, the fingerprints will be automatically calculated and sent with each certificate claim request. If you are accessing our API directly, see our [instructions for generating a lead fingerprint](https://community.activeprospect.com/posts/4112710-calculating-lead-fingerprints-with-trustedform). ## Snapshot Scanning To assist in enforcing compliance, TrustedForm can scan the certificate's HTML snapshot to ensure specific phrases are (or are not) present. If you scan for required text (disclosure terms, for example), the TrustedForm response will include a warning if that text isn't found in the snapshot. Alternately, you can scan for forbidden text (disallowed ad copy, for instance), in which case the response will include a warning if the text _is_ found. ### Scanning for Required Text To search for required text, pass the search text as the `scan` parameter when you claim the certificate. TrustedForm will then perform a case- and whitespace-insensitive search for the string. If the string is not found in the HTML document, then "string not found in snapshot" will be included in the `warnings` key of the claim response. If you'd like to search for many different strings, you'll need to use the parameter array syntax: `scan[]=example&scan[]=another%20example`. Depending on your setup, you may need to URL encode the square brackets. ### Scanning for Forbidden Text To search for forbidden text, use the `scan!` parameter in the claim call instead. If TrustedForm's case- and whitespace-insensitive search finds that text in the HTML document, then the message "string found in snapshot" will be given in the `warnings` key of the claim response. Note that aside from ignoring whitespace and text case, TrustedForm's scans are literal, including any special characters that you pass. You may include either or both of `scan` and `scan!` in a single claim call. You would then need to look for the corresponding messages in the `warnings` key of the claim response ("string not found in snapshot" or "string found in snapshot", respectively). As with scanning for required text, you may pass multiple forbidden text scans with the parameter array syntax: `scan![]=example&scan![]=another%20example`. Again, depending on your setup, you may need to URL encode the square brackets. ## Masked Certificates A [masked certificate](https://community.activeprospect.com/questions/4062880) is generated for every claim. You can obtain the URL to it from the `masked_cert_url` field of the response JSON when you claim a certificate. You can then share it with your buyers. They can claim it using the same [claiming instructions](https://community.activeprospect.com/posts/4100303-claiming-a-trustedform-certificate-via-the-api) as a normal certificate. ## Response Codes * If you successfully claim a certificate, an [HTTP 201 Created](http://en.wikipedia.org/wiki/HTTP_201) will be returned with the JSON representation of the certificate in the response body. Beware that using an HTTP GET will also return an HTTP 200 along with the HTML representation of the certificate — your cert will not be claimed with an HTTP GET. * If the certificate is older than 3 days or if the certificate URL is invalid, then an [HTTP 404 Not Found](http://en.wikipedia.org/wiki/HTTP_404) will be returned. * If you have not [authenticated](https://community.activeprospect.com/posts/4112178-trustedform-api-overview) correctly using your API key, an [HTTP 403 Forbidden](http://en.wikipedia.org/wiki/HTTP_403) will be returned. If you receive any response code other than those above, please [let us know](mailto:support@activeprospect.com). ## Pings (Deprecated) When you ping a certificate, you are requesting profile information about that particular TrustedForm Certificate. See Ping documentation for additional information on utilizing the ping method. ## Claims When you claim a certificate, a claim record is created and stored in TrustedForm and the JSON response body contains claim record. See Claim documentation for additional information on claim records. contact: name: ActiveProspect Support Team email: support@activeprospect.com url: https://support.activeprospect.com servers: - url: https://cert.trustedform.com security: - APIKey: [] tags: [] externalDocs: description: ActiveProspect Community url: https://developers.activeprospect.com/ paths: /{cert_id}/ping: get: tags: - Ping summary: Retrieve Ping Data description: | Retrieve ping data directly from a Certificate. When a lead vendor only provides a TrustedForm Certificate URL, Ping data can be retrieved directly without a Ping URL. Simply append `/ping` to the Certificate URL and perform an authenticated `GET`. A certificate's Ping data can be accessed two ways: - Querying a modified TrustedForm Certificate URL - Querying a vendor-provided TrustedForm Ping URL operationId: cert_ping parameters: - name: cert_id in: path description: Certificate ID required: true schema: type: string responses: '200': description: Ping Data content: application/json: schema: $ref: '#/components/schemas/Ping' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' deprecated: true components: schemas: Ping: type: object properties: age: type: integer format: int64 description: > Lead Age, in milliseconds. (The time elapsed between the final recorded interaction event and the call to this API) client: type: object description: Information about the user's device and browser. properties: ip: type: string description: The device's IP address. user_agent: type: string description: The browser's `User-Agent` header. dimensions: description: The device and browser visual display sizes. properties: screen: description: The device's screen dimensions. allOf: - $ref: '#/components/schemas/Dimension' window: description: The browser's screen dimensions. allOf: - $ref: '#/components/schemas/Dimension' geo: type: object description: Geographic information derived from the device's IP address. properties: city: type: string description: The device's city. country: type: string description: The device's country. postal_code: type: string description: The device's postal code. subdivisions: type: array description: | The device location's political subdivisions. States, provinces, prefectures, etc... items: type: string created_at: type: string format: date-time description: > When the certificate was issued, in [ISO8601 format](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). location: type: object description: Information about the page's location. properties: framed: type: boolean description: >- Indicates if the page that generaed the Certificate was in a frame. parent_url: type: string nullable: true description: > If the page was in a frame, the parent frame's URL. If the parent frame is the `window`, it will be the `window`'s URL. url: type: string description: The URL of the page where the Certificate was generated. time_on_page: type: integer format: int64 description: > The amount of time the user spent interacting with the page, in milliseconds. (The time elapsed between `created_at` and the final recorded interaction event) type: type: string description: >- The type of certificate associated with this response. Possible values are limited to "standard", "masked", or "facebook". Dimension: description: In pixels. properties: width: type: integer format: int64 height: type: integer format: int64 BadRequest: title: BadRequest type: object properties: message: type: string description: Malformed certificate id outcome: type: string description: error example: message: Malformed certificate id outcome: error Unauthorized: title: Unauthorized type: object properties: message: type: string description: Unauthorized outcome: type: string description: error example: message: Unauthorized outcome: error x-struct: Elixir.ClaimerWeb.Schemas.Unauthorized NotFound: title: NotFound type: object properties: message: type: string description: TrustedForm certificate has expired or could not be found outcome: type: string description: error example: message: TrustedForm certificate has expired or could not be found outcome: error x-struct: Elixir.ClaimerWeb.Schemas.NotFound responses: BadRequest: description: Malformed Certificate URL content: application/json: schema: $ref: '#/components/schemas/BadRequest' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFound: description: Certificate not found content: application/json: schema: $ref: '#/components/schemas/NotFound' securitySchemes: APIKey: type: http scheme: basic description: > TrustedForm uses [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) with the username `API` and your API key as the password. For example: `API:1f1b96c9150d8050e858c043d543bb4eadae0e6f` ````