1. Partner API v2
  2. Resources
  3. Reports

Reports

Generated PDF and Excel reports in the client's archive.
7 endpointsScope readReportReportConfigRecipientList
GET/v2/clients/{client_id}/reports
RequiresreadscopeCursor-paginatedReturns Page of Report

Reports in the client's archive, newest first. A report queued through POST /clients/{client_id}/reports is listed from the moment it is accepted, with status: pending until it is rendered and failed if it could not be, so check status before you fetch a download link. The download link is on the detail call because it is signed and short-lived.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

typestring

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
sincestring (date-time)

Only records at or after this time (RFC 3339).

limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of Report
dataarray of Report
Show item properties(8)
idstring
client_idstring
typestring

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
formatstring
One ofpdfxlsx
statusstring

pending while the report is being rendered, ready once download_url can be fetched, failed when it could not be rendered.

One ofpendingreadyfailed
periodobjectNullable
Show properties(2)
start_onstring (date)
end_onstring (date)
download_urlstringNullable

Signed, valid 24 hours. Only on the detail call and only when status is ready.

created_atstring (date-time)
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
POST/v2/clients/{client_id}/reports
RequireswritescopeReturns Report

Queues a report for the client, rendered by the same job as the dashboard's Generate button, and returns it with status: pending. Poll GET /clients/{client_id}/reports/{report_id} until status is ready, then use its download_url; a report that could not be rendered shows failed once its retry has failed too, and stays listed that way. Nobody is emailed: the report is yours to fetch, and it appears in the client's report list from the moment it is queued, with its status. Lets a partner portal produce a report on demand.

  • type is one of the client report types: executive_summary, risk_overview, phishing_overview, training_overview, training_performance, compliance, policy_acknowledgment, dark_web, monthly_report, training_status_report, manager_dept_training_report, phishing_performance. Types that need a subject the API does not take (employee_history a user, course_details a course) and the partner-level global_health_report return 400.
  • format is pdf or xlsx; xlsx is available for risk_overview only.
  • period applies to compliance (the window reported on) and phishing_overview (its length in days sets the window, which ends today). Other types have a fixed window and reject it. end_on is today or earlier where the caller is (a date up to one day ahead in UTC is accepted).
  • Limited to 5 per client per hour: 429 with Retry-After.

Send an Idempotency-Key: a retried request replays the original 202 instead of rendering a second report.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

typestringRequired

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
periodobject

Reporting window, for compliance and phishing_overview; start_on on or before end_on, end_on no later than today.

Show properties(2)
start_onstring (date)
end_onstring (date)
formatstring
One ofpdfxlsx

Default "pdf"

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "executive_summary",
    "period": {
      "start_on": "2026-09-18",
      "end_on": "2026-09-18"
    },
    "format": "pdf"
  }'
Response objectReport
idstring
client_idstring
typestring

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
formatstring
One ofpdfxlsx
statusstring

pending while the report is being rendered, ready once download_url can be fetched, failed when it could not be rendered.

One ofpendingreadyfailed
periodobjectNullable
Show properties(2)
start_onstring (date)
end_onstring (date)
download_urlstringNullable

Signed, valid 24 hours. Only on the detail call and only when status is ready.

created_atstring (date-time)
Errors400Invalid request429Too many requestsError envelope →
GET/v2/clients/{client_id}/reports/{report_id}
RequiresreadscopeReturns Report

download_url is a signed link valid for 24 hours, present once status is ready. Fetch a fresh one rather than storing it.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

report_idstringRequired

Report id, as returned by the report list.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectReport
idstring
client_idstring
typestring

Open enum.

One ofexecutive_summaryrisk_overviewphishing_overviewtraining_overviewtraining_performanceemployee_historycourse_detailscompliancepolicypolicy_acknowledgmentdark_webmonthly_reporttraining_status_reportmanager_dept_training_reportphishing_performanceglobal_health_report
formatstring
One ofpdfxlsx
statusstring

pending while the report is being rendered, ready once download_url can be fetched, failed when it could not be rendered.

One ofpendingreadyfailed
periodobjectNullable
Show properties(2)
start_onstring (date)
end_onstring (date)
download_urlstringNullable

Signed, valid 24 hours. Only on the detail call and only when status is ready.

created_atstring (date-time)
Errors404Not found within the key's accessError envelope →
GET/v2/clients/{client_id}/reports/config
RequiresreadscopeReturns ReportConfig

The reports in the client's monthly report email, the dashboard's client Settings › Reports. source says where the selection comes from: client when the client has its own selection (even one with nothing selected), partner when it follows your partner-wide selection. reports is the selection that applies either way. Nothing selected means no monthly email at all.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports/config" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectReportConfig
sourcestring

client: the client's own selection. partner: it follows your partner-wide selection.

One ofclientpartner
reportsMonthlyReportSelection

One flag per report in the monthly email. A report left out of a write is not sent.

Show properties(12)
monthly_reportboolean
executive_summaryboolean
risk_overviewboolean
risk_progressboolean
training_overviewboolean
training_status_reportboolean
training_performanceboolean
manager_dept_training_reportboolean
phishing_overviewboolean
compliance_reportboolean
framework_reportboolean
dark_web_monitoringboolean
PUT/v2/clients/{client_id}/reports/config
RequireswritescopeReturns ReportConfig

Replaces the client's own report selection, the dashboard's Save on client Settings › Reports. Send every report you want as true; a report left out is not sent. A selection with nothing true is kept as the client's own and stops its monthly email.

Send reports: null to drop the client's own selection so it follows your partner-wide selection again, the dashboard's "Use partner default". The response is the selection that now applies.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

reportsMonthlyReportSelectionRequiredNullable

One flag per report in the monthly email. A report left out of a write is not sent.

Show properties(12)
monthly_reportboolean
executive_summaryboolean
risk_overviewboolean
risk_progressboolean
training_overviewboolean
training_status_reportboolean
training_performanceboolean
manager_dept_training_reportboolean
phishing_overviewboolean
compliance_reportboolean
framework_reportboolean
dark_web_monitoringboolean
curl -X PUT "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/reports/config" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reports": {
      "monthly_report": true,
      "executive_summary": true,
      "risk_overview": true,
      "risk_progress": true,
      "training_overview": true,
      "training_status_report": true,
      "training_performance": true,
      "manager_dept_training_report": true,
      "phishing_overview": true,
      "compliance_report": true,
      "framework_report": true,
      "dark_web_monitoring": true
    }
  }'
Response objectReportConfig
sourcestring

client: the client's own selection. partner: it follows your partner-wide selection.

One ofclientpartner
reportsMonthlyReportSelection

One flag per report in the monthly email. A report left out of a write is not sent.

Show properties(12)
monthly_reportboolean
executive_summaryboolean
risk_overviewboolean
risk_progressboolean
training_overviewboolean
training_status_reportboolean
training_performanceboolean
manager_dept_training_reportboolean
phishing_overviewboolean
compliance_reportboolean
framework_reportboolean
dark_web_monitoringboolean
Errors400Invalid requestError envelope →
GET/v2/clients/{client_id}/recipients/{kind}
RequiresreadscopeReturns RecipientList

Who receives the client's monthly report or breach alerts, the dashboard's recipient picker on client Settings. Each recipient is either a person or shared mailbox from a directory (object_id), or, on a list sent by email, a typed address. route says how each one is delivered right now: direct into the mailbox, email by INFIMA's mail service, or missing when a picked recipient is no longer in its directory and is skipped. client_id is set on a recipient picked from one of your other clients (for example your own team's mailbox in your internal client).

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

kindstringRequired

monthly_report: who gets the monthly report email. breach_notification: who gets Dark Web breach alerts.

One ofmonthly_reportbreach_notification
curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/recipients/monthly_report" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectRecipientList
kindstring
One ofmonthly_reportbreach_notification
deliverystring
One ofdirectemail
can_directboolean

Whether the client's directory is connected with direct delivery on, which direct needs.

recipientsarray of Recipient
Show item properties(8)
object_idstringNullable

The directory id of a picked person or shared mailbox. Null for a typed address.

client_idstringNullable

Set when the recipient was picked from another of your clients.

client_namestringNullable

That client's name; null when your key cannot reach it.

addressstring
display_namestring
ccboolean
routestring
One ofdirectemailmissing
notestringNullable

Why a recipient goes by an unexpected route.

Errors404Not found within the key's accessError envelope →
PUT/v2/clients/{client_id}/recipients/{kind}
RequireswritescopeReturns RecipientList

Replaces the list, the dashboard's Save in the recipient picker. Each recipient is one of:

  • user_id: an INFIMA user synced from a directory, of this client or of another client your key can reach;
  • object_id (with client_id when it is from another client): a directory person or shared mailbox, as object_id reads back from GET;
  • address: a typed address, allowed only when the list is delivered by email.

delivery sets the list's mode: direct (each picked recipient gets it in their own mailbox from the client's sender; needs the client's directory connected with direct delivery on) or email (sent by INFIMA's mail service; typed addresses allowed). Leave it out to keep the list's current mode. cc puts a recipient on the CC line (monthly report only).

A recipient from another client must be in a client your key can reach and stays under the same checks at every send: if that client is deleted or leaves your account, the recipient is skipped. A recipient already on the list stays even if your key could not add it. Problems are 400: details names each recipient that is malformed or unknown (recipients[2].user_id), and recipients or delivery for a list that breaks a rule (typed_address_needs_email_delivery, direct_not_available, not_in_directory, outside_key_access). Send an empty recipients array to clear the list.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

kindstringRequired

monthly_report: who gets the monthly report email. breach_notification: who gets Dark Web breach alerts.

One ofmonthly_reportbreach_notification

Request bodyapplication/json

deliverystring
One ofdirectemail
recipientsarray of objectRequired

max 100 items

Show item properties(5)
user_idstring
object_idstring
client_idstring
addressstring (email)
ccboolean

Default false

curl -X PUT "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/recipients/monthly_report" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery": "direct",
    "recipients": [
      {
        "user_id": "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f",
        "object_id": "6f1c9a2e-0b7d-4c55-8e3a-2d9f1b7c4e60",
        "client_id": "3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10",
        "address": "it-lead@acme-mfg.com",
        "cc": false
      }
    ]
  }'
Response objectRecipientList
kindstring
One ofmonthly_reportbreach_notification
deliverystring
One ofdirectemail
can_directboolean

Whether the client's directory is connected with direct delivery on, which direct needs.

recipientsarray of Recipient
Show item properties(8)
object_idstringNullable

The directory id of a picked person or shared mailbox. Null for a typed address.

client_idstringNullable

Set when the recipient was picked from another of your clients.

client_namestringNullable

That client's name; null when your key cannot reach it.

addressstring
display_namestring
ccboolean
routestring
One ofdirectemailmissing
notestringNullable

Why a recipient goes by an unexpected route.

Errors400Invalid request404Not found within the key's accessError envelope →