{ "openapi": "3.0.4", "info": { "title": "Advancer.World Customer API", "description": "Access to your organization's programs, partners and users. Every response uses the envelope { success, message, data } plus error { code, details, traceId } on failures and page { limit, hasMore, nextCursor } on lists. Timestamps are UTC. Lists are paged with ?limit= (max 100) and ?cursor=. Limits are per organization; a 429 response carries Retry-After. Writes that send e-mails accept dryRun, and POSTs accept an Idempotency-Key header.", "version": "v1" }, "servers": [ { "url": "https://advancer.world/" } ], "paths": { "/api/v1/customer/activity": { "get": { "tags": [ "ActivityApi" ], "summary": "List what changed in your programs", "description": "Events from the progress history, oldest first: positions set or cleared, initiative progress, KPI values, awards granted, partners invited, joined or removed. Filter by period (since/until, UTC; at most 90 days, default the last 7), program, partner and types (comma-separated). Each event carries ids and names. 50 per page by default. The history starts when it was first recorded; earlier changes are not in it.", "parameters": [ { "name": "since", "in": "query", "description": "Start of the period (inclusive, ISO 8601). Default: 7 days before until.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "End of the period (exclusive, ISO 8601). Default: now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "programId", "in": "query", "description": "Only this program.", "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "query", "description": "Only this partner.", "schema": { "type": "integer", "format": "int32" } }, { "name": "types", "in": "query", "description": "Comma-separated event types, e.g. position.set,award.granted.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfActivityEventDto" } } } } } } }, "/api/v1/customer/programs/{programId}/trends": { "get": { "tags": [ "ActivityApi" ], "summary": "Get a program's trends", "description": "Per week or month: position changes (advances and setbacks), active partners, initiatives completed, KPI values reported, awards granted and partners invited, joined or removed, plus the positions per stage at the end of each period for the partners enrolled today. Rebuilt from the progress history, which starts at historyStartsAt. Default: the last 12 weeks (or 12 months); at most 53 weeks or 24 months.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "interval", "in": "query", "description": "week (default) or month.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start (ISO 8601); rounded down to the start of its week or month.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "End (ISO 8601, exclusive). Default: now.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfProgramTrendsDto" } } } } } } }, "/api/v1/customer/me": { "get": { "tags": [ "CustomerApi" ], "summary": "Get the calling organization and key", "description": "The organization, the credential in use — the API key, or the person whose AI client is calling — whether that caller may change data, and the limits that apply.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfApiMeDto" } } } } } } }, "/api/v1/customer/info": { "get": { "tags": [ "CustomerApi" ], "summary": "Get the organization's details", "description": "Name, administrator e-mail, phone and address of the organization that owns the API key.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfCustomerInfoDto" } } } } } } }, "/api/v1/customer/programs": { "get": { "tags": [ "CustomerApi" ], "summary": "List programs", "description": "The organization's programs, ordered by id. Defaults to 100 per page.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfProgramInfoDto" } } } } } } }, "/api/v1/customer/programs/search": { "get": { "tags": [ "CustomerApi" ], "summary": "Search programs by name", "description": "Programs whose name contains q (case-insensitive), ordered by id. Defaults to 100 per page.", "parameters": [ { "name": "q", "in": "query", "description": "Text to look for in the program name.", "required": true, "schema": { "maxLength": 100, "minLength": 1, "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfProgramInfoDto" } } } } } } }, "/api/v1/customer/users": { "get": { "tags": [ "CustomerApi" ], "summary": "List users", "description": "Users of the organization, including inactive ones, ordered by id. Defaults to 100 per page.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfUserInfoDto" } } } } } } }, "/api/v1/customer/users/search": { "get": { "tags": [ "CustomerApi" ], "summary": "Search users by name or e-mail", "description": "Users whose name or e-mail contains q (case-insensitive), ordered by id. Defaults to 100 per page.", "parameters": [ { "name": "q", "in": "query", "description": "Text to look for in the name or e-mail.", "required": true, "schema": { "maxLength": 100, "minLength": 1, "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfUserInfoDto" } } } } } } }, "/api/v1/customer/users/{email}": { "put": { "tags": [ "CustomerApi" ], "summary": "Update a user found by e-mail", "description": "The v1 form of PATCH users/{userId}: updates the name, phone and job title of a user of the organization, found by e-mail. A new e-mail address is only requested: it applies once confirmed from that address, and shows as pendingEmailAddress in the response until then.", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfLegacyUserUpdateResultDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners": { "get": { "tags": [ "CustomerApi" ], "summary": "List a program's partners", "description": "Partners linked to a program of the organization, with their status and when they were invited, opened the invitation and accepted it (invitations not yet accepted are included). Ordered by partner id; 100 per page by default. 404 when the program doesn't exist or belongs to another organization.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfProgramPartnerDto" } } } } } } }, "/api/v1/customer/programs/{programId}/enrollments": { "post": { "tags": [ "EnrollmentsApi" ], "summary": "Enroll a partner in a program", "description": "Adds a partner to a program, by e-mail or by partnerId. A registered partner that is already in one of your programs joins at once (outcome enrolled) and its administrators are told. Any other partner is invited (outcome invited): a new partner is created and e-mailed a registration link, and a registered partner outside your programs gets an invitation notice. Enrolling a partner that is already in the program changes nothing (outcome already_enrolled). Invitations count toward the daily invitation limit (invitation_limit_reached), and nobody is e-mailed twice within 2 hours (emailStatus skipped_recently_contacted). Supports dryRun and the Idempotency-Key header. 404 when the program or partnerId isn't yours; email_unavailable when the address belongs to a user who isn't a partner administrator.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique value per operation (e.g. a UUID), to retry safely: for 24 hours, a request with the same key gets the first successful response again (with the Idempotent-Replayed header) instead of repeating the operation.", "schema": { "maxLength": 100, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentCreateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EnrollmentCreateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EnrollmentCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfEnrollmentResultDto" } } } } } } }, "/api/v1/customer/programs/{programId}/enrollments/{partnerId}": { "delete": { "tags": [ "EnrollmentsApi" ], "summary": "Remove a partner from a program", "description": "Ends a partner's enrollment, accepted or not, and tells its administrators unless notify=false. The partner's positions, answers and other progress are kept: enrolling it again restores them. Supports dryRun. 404 when the program isn't yours or the partner isn't in it.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "notify", "in": "query", "description": "E-mail the partner's administrators. Default true.", "schema": { "type": "boolean", "default": true } }, { "name": "dryRun", "in": "query", "description": "Return what would happen without changing anything.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfEnrollmentRemovalDto" } } } } } } }, "/api/v1/customer/programs/{programId}/enrollments/{partnerId}/invitation": { "post": { "tags": [ "EnrollmentsApi" ], "summary": "Send a partner's invitation again", "description": "E-mails a new invitation link for an enrollment the partner hasn't accepted yet; earlier links stop working. invitedAt becomes now. Refused with already_accepted when the partner already joined, and with resend_too_soon (and Retry-After) when the partner was e-mailed less than 2 hours ago. Counts toward the daily invitation limit. Supports dryRun and the Idempotency-Key header.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "dryRun", "in": "query", "description": "Return what would happen without sending anything.", "schema": { "type": "boolean", "default": false } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique value per operation (e.g. a UUID), to retry safely: for 24 hours, a request with the same key gets the first successful response again (with the Idempotent-Replayed header) instead of repeating the operation.", "schema": { "maxLength": 100, "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfInvitationResendDto" } } } } } } }, "/api/v1/customer/kpis": { "get": { "tags": [ "KpisApi" ], "summary": "List KPIs", "description": "Your organization's KPI definitions, ordered by id; 50 per page by default.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfKpiDto" } } } } } } }, "/api/v1/customer/partners": { "get": { "tags": [ "PartnersApi" ], "summary": "List partners", "description": "Partners enrolled in your programs, ordered by id; 50 per page by default. Filter by text, program or registration status.", "parameters": [ { "name": "q", "in": "query", "description": "Text to look for in the name or administrator e-mail.", "schema": { "maxLength": 100, "minLength": 0, "type": "string" } }, { "name": "programId", "in": "query", "description": "Only partners enrolled in this program.", "schema": { "type": "integer", "format": "int32" } }, { "name": "status", "in": "query", "description": "invited or registered.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfPartnerSummaryDto" } } } } } } }, "/api/v1/customer/partners/{partnerId}": { "get": { "tags": [ "PartnersApi" ], "summary": "Get a partner", "description": "Profile, enrollments in your programs (invited, viewed, accepted) and awards received in your programs. 404 for a partner that isn't enrolled in any of your programs.", "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfPartnerDetailDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/{partnerId}/positions/{subTopicId}": { "put": { "tags": [ "PositionsApi" ], "summary": "Set a partner's position in a subtopic", "description": "Places the partner at a state of the subtopic (a stage of that theme), replacing its current one. Repeating the request changes nothing (changed: false). Only in manual-mode programs: program_mode_not_manual otherwise, because in self-assessment programs partners place themselves and in automatic ones completing the work moves them. 404 when the program isn't yours, the partner isn't in it or the subtopic isn't part of it; validation_failed when the state belongs to another subtopic.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "subTopicId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionSetRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PositionSetRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PositionSetRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfPositionChangeDto" } } } } } }, "delete": { "tags": [ "PositionsApi" ], "summary": "Clear a partner's position in a subtopic", "description": "Removes the partner's position in the subtopic. When it has none, nothing changes (changed: false). Same rules as setting a position: manual-mode programs only.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "subTopicId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfPositionChangeDto" } } } } } } }, "/api/v1/customer/programs/{programId}": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get a program", "description": "The program with its stages, topics and subtopics (ids, names and order) and live counts. Descriptions and other design content are not included.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfProgramDetailDto" } } } } } } }, "/api/v1/customer/programs/{programId}/structure": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get a program's grid structure", "description": "The states (one per stage and subtopic) and the transitions between them, with the number of work items on each transition. Use it to read positions and scorecards.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfProgramStructureDto" } } } } } } }, "/api/v1/customer/programs/{programId}/progress": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get where partners are in a program", "description": "How the enrolled partners are spread over the stages, overall and per subtopic, computed live.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfProgramProgressDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/progress": { "get": { "tags": [ "ProgramsApi" ], "summary": "List the progress of each partner in a program", "description": "One summary per enrolled partner: subtopics positioned, average and lowest stage, last activity. Ordered by partner id; 50 per page by default.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfPartnerProgressSummaryDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/{partnerId}/progress": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get a partner's scorecard in a program", "description": "The partner's current state in each subtopic and the next step: its initiatives, surveys, signatures and uploads with their status, and whether it is complete by the automatic progression rule. Plus the partner's awards in the program.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfPartnerScorecardDto" } } } } } } }, "/api/v1/customer/programs/{programId}/kpis": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get KPI statistics of a program", "description": "For each KPI linked to a state of the program: how many enrolled partners reported a value, and the average, minimum, maximum and standard deviation (quantitative KPIs) or the share of yes (qualitative KPIs).", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfProgramKpiStatDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/{partnerId}/kpis": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get a partner's KPI values in a program", "description": "The latest value the partner reported for each KPI and state of the program.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfPartnerKpiValueDto" } } } } } } }, "/api/v1/customer/programs/{programId}/awards": { "get": { "tags": [ "ProgramsApi" ], "summary": "List a program's awards", "description": "Award definitions: validity, whether all or any condition is needed, the conditions, and how many partners received each.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfAwardDefinitionDto" } } } } } } }, "/api/v1/customer/programs/{programId}/awards/grants": { "get": { "tags": [ "ProgramsApi" ], "summary": "List the awards granted in a program", "description": "Who received which award and when, whether it is still valid, and its public verification link. Ordered by award then partner; 50 per page by default.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "awardId", "in": "query", "description": "Only this award.", "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "query", "description": "Only this partner.", "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfPartnerAwardDto" } } } } } } }, "/api/v1/customer/programs/{programId}/work": { "get": { "tags": [ "ProgramsApi" ], "summary": "List the work items of a program", "description": "Every initiative, survey, signature request and upload request of the program, with where it sits on the grid and how the enrolled partners stand on it. This is the view the scorecard cannot give: the scorecard reports only a partner's next transition, so an item a partner has already passed is invisible there. Counts in rollup are always out of enrolledPartners. Ordered by kind then id; 50 per page by default.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "type", "in": "query", "description": "Only this kind: initiative, survey, signature or upload.", "schema": { "type": "string" } }, { "name": "transitionId", "in": "query", "description": "Only the items of this transition.", "schema": { "type": "integer", "format": "int32" } }, { "name": "subTopicId", "in": "query", "description": "Only the items on this subtopic.", "schema": { "type": "integer", "format": "int32" } }, { "name": "q", "in": "query", "description": "Text to look for in the item's name.", "schema": { "maxLength": 100, "minLength": 0, "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfProgramWorkIndexDto" } } } } } } }, "/api/v1/customer/programs/{programId}/transitions/{transitionId}/work": { "get": { "tags": [ "ProgramsApi" ], "summary": "Get the work of one transition, partner by partner", "description": "How every enrolled partner stands on the work of one transition: who has answered a survey, who has uploaded, how far each initiative has got. rollup covers every enrolled partner; partners is a page of them, 50 at a time. A transition of another program, or of another organization, answers 404.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "transitionId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfTransitionWorkDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/{partnerId}/kpis/{kpiId}": { "put": { "tags": [ "ReportingApi" ], "summary": "Record a KPI value for a partner", "description": "Records the value a partner reports for a KPI on one state, replacing the value it had there. Repeating the same value changes nothing (changed: false). For a qualitative KPI anything other than 0 means yes. In the web app only the partner can enter this; recording it here is done on its behalf and the progress history keeps who did it. 404 when the program isn't yours, the partner isn't in it or the state isn't part of it; validation_failed when the KPI isn't linked to that state. The response carries the KPI's targetValue when it has one, but no pass/fail: nothing records whether higher or lower is better.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "kpiId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KpiValueRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/KpiValueRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/KpiValueRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfKpiValueChangeDto" } } } } } } }, "/api/v1/customer/programs/{programId}/partners/{partnerId}/initiatives/{initiativeId}": { "put": { "tags": [ "ReportingApi" ], "summary": "Record a partner's progress on an initiative", "description": "Records how far a partner has got on an initiative, 0 to 100. Repeating the same progress changes nothing (changed: false). In an automatic-mode program this can complete a transition and move the partner on the grid; positionChanged says whether it did, and the scorecard shows where they are now. 404 when the program isn't yours, the partner isn't in it, or the initiative isn't part of it.", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "initiativeId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiativeProgressRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InitiativeProgressRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InitiativeProgressRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfInitiativeProgressChangeDto" } } } } } } }, "/api/v1/customer/users/{userId}": { "get": { "tags": [ "UsersApi" ], "summary": "Get a user", "description": "One user of the organization, with the new e-mail address waiting for confirmation if there is one. 404 when the user belongs to another organization.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfUserDetailDto" } } } } } }, "patch": { "tags": [ "UsersApi" ], "summary": "Update a user", "description": "Changes the fields that are sent. A new e-mail address isn't applied at once: the new address gets a confirmation link (valid 48 hours) and the current one a notice, and the address shows as pendingEmailAddress until the link is opened. email_unavailable when another account uses the address; resend_too_soon when another address was requested less than 2 hours ago.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserUpdateDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfUserDetailDto" } } } } } } }, "/api/v1/customer/users/invitations": { "post": { "tags": [ "UsersApi" ], "summary": "Invite a user", "description": "E-mails an invitation to join the organization as a user; invited users are never administrators. An address already invited and not registered gets the invitation again (outcome invitation_resent), at most once every 2 hours (resend_too_soon). already_registered when the user has registered; email_unavailable when the address belongs to another Advancer account. Counts toward the daily invitation limit. Supports dryRun and the Idempotency-Key header.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique value per operation (e.g. a UUID), to retry safely: for 24 hours, a request with the same key gets the first successful response again (with the Idempotent-Replayed header) instead of repeating the operation.", "schema": { "maxLength": 100, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInvitationRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserInvitationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfUserInvitationResultDto" } } } } } } } }, "components": { "schemas": { "ActivityEventDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "Increases with every event; also the paging key.", "format": "int64" }, "type": { "type": "string", "description": "position.set, position.cleared, initiative.progress, kpi.value_set, award.granted, enrollment.invited, enrollment.accepted or enrollment.removed." }, "occurredAt": { "type": "string", "description": "UTC.", "format": "date-time" }, "programId": { "type": "integer", "format": "int32" }, "programTitle": { "type": "string" }, "partnerId": { "type": "integer", "format": "int32" }, "partnerName": { "type": "string" }, "subTopicId": { "type": "integer", "format": "int32", "nullable": true }, "subTopicName": { "type": "string", "nullable": true }, "stateId": { "type": "integer", "description": "The partner's new state (position events).", "format": "int32", "nullable": true }, "stageId": { "type": "integer", "format": "int32", "nullable": true }, "stageName": { "type": "string", "nullable": true }, "previousStateId": { "type": "integer", "description": "The state the partner left (position events).", "format": "int32", "nullable": true }, "previousStageName": { "type": "string", "nullable": true }, "entityId": { "type": "integer", "description": "The initiative, KPI or award the event is about.", "format": "int32", "nullable": true }, "entityName": { "type": "string", "nullable": true }, "value": { "type": "number", "description": "Initiative progress (0-100) or KPI value.", "format": "double", "nullable": true }, "previousValue": { "type": "number", "format": "double", "nullable": true }, "source": { "type": "string", "description": "Who made the change: partner, customer, automatic (automatic progression), job (daily processing) or api." }, "apiKeyId": { "type": "integer", "description": "Your API key that made the change, when source is api.", "format": "int32", "nullable": true } } }, "ApiAwardConditionType": { "enum": [ "unknown", "complete_stage", "reach_state", "complete_initiative" ] }, "ApiAwardLogic": { "enum": [ "all", "any" ], "description": "all: every condition must be met; any: one is enough." }, "ApiAwardValidityKind": { "enum": [ "months", "perpetual", "while_conditions_met" ], "description": "months: expires that many months after it was granted; perpetual: never expires; while_conditions_met: meant to last while the conditions hold (currently not enforced, so it doesn't expire)." }, "ApiEmailStatus": { "enum": [ "sent", "failed", "not_requested", "skipped_recently_contacted", "no_recipient", "would_send", "none" ] }, "ApiEnrollmentOutcome": { "enum": [ "enrolled", "invited", "already_enrolled" ] }, "ApiErrorDetail": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, "ApiErrorInfo": { "type": "object", "properties": { "code": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ApiErrorDetail" }, "nullable": true }, "traceId": { "type": "string", "nullable": true } }, "nullable": true }, "ApiMeCustomerDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" } } }, "ApiMeDto": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/ApiMeCustomerDto" }, "apiKey": { "$ref": "#/components/schemas/ApiMeKeyDto" }, "user": { "$ref": "#/components/schemas/ApiMeUserDto" }, "limits": { "$ref": "#/components/schemas/ApiMeLimitsDto" }, "canWrite": { "type": "boolean", "description": "Whether this caller may use the endpoints that change data." }, "writeBlockers": { "type": "array", "items": { "type": "string" }, "description": "Why CanWrite is false; empty when it is true. Codes, not messages: not_customer_admin." } }, "nullable": true }, "ApiMeKeyDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "description": "UTC.", "format": "date-time" }, "lastUsedAt": { "type": "string", "description": "UTC, updated at most every 15 minutes.", "format": "date-time", "nullable": true } }, "nullable": true }, "ApiMeLimitsDto": { "type": "object", "properties": { "readPerMinute": { "type": "integer", "description": "Requests per minute for read operations, per organization.", "format": "int32" }, "writePerMinute": { "type": "integer", "description": "Requests per minute for write operations, per organization.", "format": "int32" }, "dailyQuota": { "type": "integer", "description": "Requests per organization in a rolling 24-hour window.", "format": "int32" }, "maxPageSize": { "type": "integer", "format": "int32" } } }, "ApiMeUserDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "email": { "type": "string" }, "isCustomerAdmin": { "type": "boolean", "description": "Administrators of the organization are the only people who may change data through the API." } }, "nullable": true }, "ApiPageInfo": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "nullable": true }, "ApiPartnerStatus": { "enum": [ "invited", "registered" ] }, "ApiProgramMode": { "enum": [ "unknown", "self_assessment", "automatic", "manual" ], "description": "How partners move between states: self_assessment (the partner sets its own state), automatic (moves when a transition's work is complete) or manual (the program owner sets it)." }, "ApiProgramMode2": { "enum": [ "unknown", "self_assessment", "automatic", "manual" ] }, "ApiResponseOfApiMeDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ApiMeDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfCustomerInfoDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/CustomerInfoDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfEnrollmentRemovalDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/EnrollmentRemovalDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfEnrollmentResultDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/EnrollmentResultDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfInitiativeProgressChangeDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/InitiativeProgressChangeDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfInvitationResendDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/InvitationResendDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfKpiValueChangeDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/KpiValueChangeDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfLegacyUserUpdateResultDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/LegacyUserUpdateResultDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfActivityEventDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEventDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfAwardDefinitionDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AwardDefinitionDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfKpiDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KpiDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfPartnerAwardDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAwardDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfPartnerKpiValueDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerKpiValueDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfPartnerProgressSummaryDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerProgressSummaryDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfPartnerSummaryDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerSummaryDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfProgramInfoDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramInfoDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfProgramKpiStatDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramKpiStatDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfProgramPartnerDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramPartnerDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfListOfUserInfoDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfoDto" }, "nullable": true }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfPartnerDetailDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PartnerDetailDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfPartnerScorecardDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PartnerScorecardDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfPositionChangeDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PositionChangeDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfProgramDetailDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ProgramDetailDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfProgramProgressDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ProgramProgressDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfProgramStructureDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ProgramStructureDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfProgramTrendsDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ProgramTrendsDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfProgramWorkIndexDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ProgramWorkIndexDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfTransitionWorkDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/TransitionWorkDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfUserDetailDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/UserDetailDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiResponseOfUserInvitationResultDto": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/UserInvitationResultDto" }, "error": { "$ref": "#/components/schemas/ApiErrorInfo" }, "page": { "$ref": "#/components/schemas/ApiPageInfo" } } }, "ApiSignatureStatus": { "enum": [ "not_started", "pending", "viewed", "completed", "declined", "expired" ] }, "ApiTrendInterval": { "enum": [ "week", "month" ] }, "ApiUploadStatus": { "enum": [ "not_started", "opened", "submitted" ] }, "ApiUserInvitationOutcome": { "enum": [ "invited", "invitation_resent" ] }, "ApiWorkItemType": { "enum": [ "initiative", "survey", "signature", "upload" ] }, "AwardConditionDto": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ApiAwardConditionType" }, "entityId": { "type": "integer", "description": "The stage, state or initiative id, depending on the type.", "format": "int32" } } }, "AwardDefinitionDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" }, "retroactive": { "type": "boolean", "description": "When false, only progress made after the award was created counts." }, "validity": { "$ref": "#/components/schemas/AwardValidityDto" }, "logic": { "$ref": "#/components/schemas/ApiAwardLogic" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/AwardConditionDto" } }, "granted": { "type": "integer", "description": "Partners that have received the award.", "format": "int32" } } }, "AwardValidityDto": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/ApiAwardValidityKind" }, "months": { "type": "integer", "format": "int32", "nullable": true } } }, "CustomerInfoDto": { "type": "object", "properties": { "organizationName": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string", "nullable": true }, "streetAddress": { "type": "string" }, "postalCode": { "type": "string" }, "cityName": { "type": "string" }, "countryName": { "type": "string" } }, "nullable": true }, "EnrollmentCreateRequest": { "type": "object", "properties": { "email": { "maxLength": 255, "minLength": 0, "type": "string", "description": "E-mail address of the partner's administrator. A partner that isn't on Advancer yet is created and invited to register. Send email or partnerId, not both.", "nullable": true }, "partnerId": { "type": "integer", "description": "A partner already enrolled in one of your programs (see GET partners). Send email or partnerId, not both.", "format": "int32", "nullable": true }, "notify": { "type": "boolean", "description": "Send the invitation or enrollment e-mail. Default true. An invitation sent without e-mail can be sent later with POST programs/{programId}/enrollments/{partnerId}/invitation." }, "dryRun": { "type": "boolean", "description": "Check the request and return what would happen, without changing anything or sending e-mails." } } }, "EnrollmentDatesDto": { "type": "object", "properties": { "invitedAt": { "type": "string", "format": "date-time", "nullable": true }, "viewedAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "EnrollmentDatesDto2": { "type": "object", "properties": { "invitedAt": { "type": "string", "format": "date-time", "nullable": true }, "viewedAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true } }, "description": "Null in a dry run that would create the enrollment.", "nullable": true }, "EnrollmentRemovalDto": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "emailStatus": { "$ref": "#/components/schemas/ApiEmailStatus" } }, "nullable": true }, "EnrollmentResultDto": { "type": "object", "properties": { "outcome": { "$ref": "#/components/schemas/ApiEnrollmentOutcome" }, "dryRun": { "type": "boolean" }, "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "description": "Null in a dry run that would create the partner.", "format": "int32", "nullable": true }, "partnerName": { "type": "string", "description": "Empty until an invited partner completes its registration." }, "partnerStatus": { "$ref": "#/components/schemas/ApiPartnerStatus" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentDatesDto2" }, "emailStatus": { "$ref": "#/components/schemas/ApiEmailStatus" } }, "nullable": true }, "InitiativeProgressChangeDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "initiativeId": { "type": "integer", "format": "int32" }, "initiativeName": { "type": "string" }, "transitionId": { "type": "integer", "description": "The transition this initiative belongs to, and the subtopic that transition is on.", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" }, "progress": { "type": "number", "format": "double" }, "previousProgress": { "type": "number", "description": "Null when the partner had never reported progress on this initiative.", "format": "double", "nullable": true }, "complete": { "type": "boolean", "description": "True at 100 or more." }, "changed": { "type": "boolean", "description": "False when the progress was already the one given, in which case nothing was written." }, "startedOn": { "type": "string", "format": "date", "nullable": true }, "updatedAt": { "type": "string", "description": "UTC. Null in a dry run.", "format": "date-time", "nullable": true }, "positionChanged": { "type": "boolean", "description": "True when this report moved the partner on the grid. Only happens in an automatic-mode program, where completing the work of a transition advances the partner; read the scorecard to see where they are now." }, "dryRun": { "type": "boolean" } }, "nullable": true }, "InitiativeProgressRequest": { "required": [ "progress" ], "type": "object", "properties": { "progress": { "maximum": 100, "minimum": 0, "type": "number", "description": "How far the partner has got, 0 to 100. 100 completes the initiative.", "format": "double", "nullable": true }, "startedOn": { "type": "string", "description": "The date the partner started, yyyy-MM-dd. Kept as it is when omitted; set to today on the first report if never given.", "format": "date", "nullable": true }, "dryRun": { "type": "boolean", "description": "Check the request and report what would happen, without recording anything." } } }, "InitiativeStatusDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "progress": { "type": "number", "description": "0 to 100.", "format": "double" }, "startedOn": { "type": "string", "description": "Start date given by the partner.", "format": "date", "nullable": true }, "updatedAt": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "complete": { "type": "boolean" } } }, "InvitationResendDto": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "emailStatus": { "$ref": "#/components/schemas/ApiEmailStatus" }, "invitedAt": { "type": "string", "description": "UTC. Set to the time of this invitation.", "format": "date-time", "nullable": true } }, "nullable": true }, "KpiDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "qualitative": { "type": "boolean", "description": "Qualitative KPIs are yes/no: any value other than 0 means yes." }, "primary": { "type": "boolean" }, "calculationMethod": { "type": "string", "nullable": true }, "targetValue": { "type": "number", "format": "double", "nullable": true }, "createdDate": { "type": "string", "description": "UTC.", "format": "date-time" } } }, "KpiValueChangeDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "kpiId": { "type": "integer", "format": "int32" }, "kpiName": { "type": "string" }, "stateId": { "type": "integer", "format": "int32" }, "qualitative": { "type": "boolean", "description": "A qualitative KPI is a yes/no: any value other than 0 is yes." }, "value": { "type": "number", "format": "double" }, "previousValue": { "type": "number", "description": "Null when the partner had never reported this KPI on this state.", "format": "double", "nullable": true }, "changed": { "type": "boolean", "description": "False when the value was already the one given, in which case nothing was written." }, "updatedAt": { "type": "string", "description": "UTC. Null in a dry run.", "format": "date-time", "nullable": true }, "targetValue": { "type": "number", "description": "The target on the KPI definition, when it has one. Whether higher or lower is better is not recorded anywhere, so no pass/fail is computed.", "format": "double", "nullable": true }, "dryRun": { "type": "boolean" } }, "nullable": true }, "KpiValueRequest": { "required": [ "stateId", "value" ], "type": "object", "properties": { "stateId": { "type": "integer", "description": "The state the value is reported against. A KPI is linked to states; see GET programs/{programId}/kpis for the states each KPI is on.", "format": "int32", "nullable": true }, "value": { "type": "number", "description": "The value. For a qualitative KPI anything other than 0 means yes.", "format": "double", "nullable": true }, "dryRun": { "type": "boolean", "description": "Check the request and report what would happen, without recording anything." } } }, "LegacyUserUpdateResultDto": { "type": "object", "properties": { "message": { "type": "string" }, "pendingEmailAddress": { "type": "string", "description": "Set when the request asked for a new e-mail address: it applies once confirmed from that address.", "nullable": true } }, "nullable": true }, "NextStepDto": { "type": "object", "properties": { "transitionId": { "type": "integer", "format": "int32" }, "toStateId": { "type": "integer", "format": "int32" }, "toStageId": { "type": "integer", "format": "int32" }, "toStageName": { "type": "string" }, "complete": { "type": "boolean", "description": "True when all initiatives are at 100%, all required survey questions are answered and all signatures are completed: the rule automatic progression uses. Uploads don't count." }, "initiatives": { "type": "array", "items": { "$ref": "#/components/schemas/InitiativeStatusDto" } }, "surveys": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyStatusDto" } }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureStatusDto" } }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/UploadStatusDto" } } }, "description": "The step out of the current state (the first step when not positioned); null at the last state.", "nullable": true }, "PartnerAwardDto": { "type": "object", "properties": { "awardId": { "type": "integer", "format": "int32" }, "awardName": { "type": "string" }, "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "partnerName": { "type": "string" }, "awardedOn": { "type": "string", "description": "Date the award was granted.", "format": "date" }, "expiresOn": { "type": "string", "description": "Date the award expires; null when it doesn't expire.", "format": "date", "nullable": true }, "valid": { "type": "boolean" }, "verificationUrl": { "type": "string", "description": "Public page anyone can open to check the award." } } }, "PartnerDetailDto": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ApiPartnerStatus" }, "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEnrollmentDto" } }, "awards": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAwardDto" } }, "id": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "category": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string", "nullable": true }, "streetAddress": { "type": "string" }, "postalCode": { "type": "string" }, "cityName": { "type": "string" }, "countryName": { "type": "string" }, "registrationDate": { "type": "string", "description": "UTC. Null while the partner has not completed its registration.", "format": "date-time", "nullable": true }, "enabled": { "type": "boolean" } }, "nullable": true }, "PartnerEnrollmentDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "programTitle": { "type": "string" }, "invitedAt": { "type": "string", "format": "date-time", "nullable": true }, "viewedAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "PartnerKpiValueDto": { "type": "object", "properties": { "kpiId": { "type": "integer", "format": "int32" }, "kpiName": { "type": "string" }, "qualitative": { "type": "boolean" }, "stateId": { "type": "integer", "format": "int32" }, "value": { "type": "number", "format": "double" }, "targetValue": { "type": "number", "description": "The target on the KPI definition, when it has one. No pass/fail is computed: whether higher or lower is better is not recorded.", "format": "double", "nullable": true }, "updatedAt": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true } } }, "PartnerProgressSummaryDto": { "type": "object", "properties": { "partnerId": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApiPartnerStatus" }, "positionedSubTopics": { "type": "integer", "format": "int32" }, "totalSubTopics": { "type": "integer", "format": "int32" }, "averageStageOrder": { "type": "number", "format": "double", "nullable": true }, "minimumStageOrder": { "type": "integer", "format": "int32", "nullable": true }, "lastActivityAt": { "type": "string", "description": "UTC. Latest position change, initiative update, KPI value, survey answer, upload or signature in this program.", "format": "date-time", "nullable": true } } }, "PartnerScorecardDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "mode": { "$ref": "#/components/schemas/ApiProgramMode2" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentDatesDto" }, "summary": { "$ref": "#/components/schemas/ScorecardSummaryDto" }, "subTopics": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardSubTopicDto" } }, "awards": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAwardDto" } } }, "nullable": true }, "PartnerSummaryDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "category": { "type": "string" }, "countryName": { "type": "string", "nullable": true }, "contactEmail": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApiPartnerStatus" }, "registrationDate": { "type": "string", "description": "UTC. Null while the partner has not completed its registration.", "format": "date-time", "nullable": true }, "programIds": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Your programs the partner is enrolled in." } } }, "PositionChangeDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "partnerId": { "type": "integer", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" }, "stateId": { "type": "integer", "description": "The partner's state in the subtopic; null when it has none.", "format": "int32", "nullable": true }, "stageId": { "type": "integer", "format": "int32", "nullable": true }, "stageName": { "type": "string", "nullable": true }, "previousStateId": { "type": "integer", "description": "The state the partner left, when the request changed it.", "format": "int32", "nullable": true }, "changed": { "type": "boolean", "description": "False when nothing had to change: the partner was already at that state (PUT) or had none (DELETE)." }, "setAt": { "type": "string", "description": "UTC. When the partner was placed at the current state.", "format": "date-time", "nullable": true } }, "nullable": true }, "PositionDto": { "type": "object", "properties": { "stateId": { "type": "integer", "format": "int32" }, "stageId": { "type": "integer", "format": "int32" }, "stageName": { "type": "string" }, "stageOrder": { "type": "integer", "format": "int32" }, "setAt": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true } }, "description": "The partner's current state; null when not positioned in this subtopic.", "nullable": true }, "PositionSetRequest": { "required": [ "stateId" ], "type": "object", "properties": { "stateId": { "type": "integer", "description": "A state of this subtopic, i.e. the stage the partner is at in it (see GET programs/{programId}/structure).", "format": "int32", "nullable": true } } }, "ProgramCountsDto": { "type": "object", "properties": { "stages": { "type": "integer", "format": "int32" }, "topics": { "type": "integer", "format": "int32" }, "subTopics": { "type": "integer", "format": "int32" }, "states": { "type": "integer", "format": "int32" }, "transitions": { "type": "integer", "format": "int32" }, "enrolledPartners": { "type": "integer", "format": "int32" }, "awards": { "type": "integer", "format": "int32" }, "kpis": { "type": "integer", "description": "Distinct KPIs linked to the program's states.", "format": "int32" } } }, "ProgramDetailDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "createdDate": { "type": "string", "description": "UTC.", "format": "date-time" }, "enabled": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/ApiProgramMode2" }, "counts": { "$ref": "#/components/schemas/ProgramCountsDto" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/StageDto" }, "description": "Maturity stages, in order." }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/TopicDto" }, "description": "Topics and their subtopics, in order." } }, "nullable": true }, "ProgramInfoDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "createdDate": { "type": "string", "description": "UTC.", "format": "date-time" }, "enabled": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/ApiProgramMode" } } }, "ProgramKpiStatDto": { "type": "object", "properties": { "kpiId": { "type": "integer", "format": "int32" }, "kpiName": { "type": "string" }, "qualitative": { "type": "boolean" }, "targetValue": { "type": "number", "format": "double", "nullable": true }, "stateId": { "type": "integer", "format": "int32" }, "stageId": { "type": "integer", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" }, "reportingPartners": { "type": "integer", "format": "int32" }, "average": { "type": "number", "description": "Quantitative KPIs only.", "format": "double", "nullable": true }, "minimum": { "type": "number", "description": "Quantitative KPIs only.", "format": "double", "nullable": true }, "maximum": { "type": "number", "description": "Quantitative KPIs only.", "format": "double", "nullable": true }, "standardDeviation": { "type": "number", "description": "Population standard deviation. Quantitative KPIs only.", "format": "double", "nullable": true }, "yesShare": { "type": "number", "description": "Share (0 to 1) of reporting partners that answered yes. Qualitative KPIs only.", "format": "double", "nullable": true } } }, "ProgramPartnerDto": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ApiPartnerStatus" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentDatesDto" }, "id": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "category": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string", "nullable": true }, "streetAddress": { "type": "string" }, "postalCode": { "type": "string" }, "cityName": { "type": "string" }, "countryName": { "type": "string" }, "registrationDate": { "type": "string", "description": "UTC. Null while the partner has not completed its registration.", "format": "date-time", "nullable": true }, "enabled": { "type": "boolean" } } }, "ProgramProgressDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "mode": { "$ref": "#/components/schemas/ApiProgramMode2" }, "enrolledPartners": { "type": "integer", "format": "int32" }, "positionedPartners": { "type": "integer", "description": "Enrolled partners with a current state in at least one subtopic.", "format": "int32" }, "averageStageOrder": { "type": "number", "description": "Mean stage order over all current states of enrolled partners; null when nobody is positioned.", "format": "double", "nullable": true }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/StageDistributionDto" } }, "subTopics": { "type": "array", "items": { "$ref": "#/components/schemas/SubTopicDistributionDto" } } }, "nullable": true }, "ProgramStructureDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StructureStateDto" }, "description": "One state per stage and subtopic: the cell of the grid." }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StructureTransitionDto" }, "description": "Steps from one state to the next within a subtopic, with the number of work items attached." } }, "nullable": true }, "ProgramTrendsDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "interval": { "$ref": "#/components/schemas/ApiTrendInterval" }, "historyStartsAt": { "type": "string", "description": "UTC. The history is recorded from this moment; periods before it are incomplete. Null when nothing was recorded yet.", "format": "date-time", "nullable": true }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/TrendStageDto" }, "description": "The program's stages, in order, as used by positionsPerStage." }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/TrendPeriodDto" } } }, "nullable": true }, "ProgramWorkIndexDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "enrolledPartners": { "type": "integer", "description": "Every count in this response is out of this many partners.", "format": "int32" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItemDto" } } }, "nullable": true }, "ScorecardSubTopicDto": { "type": "object", "properties": { "topicId": { "type": "integer", "format": "int32" }, "topicName": { "type": "string" }, "subTopicId": { "type": "integer", "format": "int32" }, "subTopicName": { "type": "string" }, "position": { "$ref": "#/components/schemas/PositionDto" }, "next": { "$ref": "#/components/schemas/NextStepDto" } } }, "ScorecardSummaryDto": { "type": "object", "properties": { "positionedSubTopics": { "type": "integer", "format": "int32" }, "totalSubTopics": { "type": "integer", "format": "int32" }, "completedSubTopics": { "type": "integer", "description": "Subtopics where the partner is at the last state.", "format": "int32" }, "averageStageOrder": { "type": "number", "format": "double", "nullable": true }, "minimumStageOrder": { "type": "integer", "format": "int32", "nullable": true } } }, "SignatureStatusDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApiSignatureStatus" }, "signedAt": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "complete": { "type": "boolean" } } }, "StageCountDto": { "type": "object", "properties": { "stageId": { "type": "integer", "format": "int32" }, "partners": { "type": "integer", "format": "int32" } } }, "StageDistributionDto": { "type": "object", "properties": { "stageId": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "partnersAtMinimumStage": { "type": "integer", "description": "Partners whose lowest current stage, over all subtopics, is this one.", "format": "int32" }, "positions": { "type": "integer", "description": "Current states at this stage, over all partners and subtopics.", "format": "int32" } } }, "StageDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" } } }, "StructureStateDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "stageId": { "type": "integer", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" } } }, "StructureTransitionDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" }, "fromStateId": { "type": "integer", "format": "int32" }, "toStateId": { "type": "integer", "format": "int32" }, "workItems": { "$ref": "#/components/schemas/WorkItemCountsDto" } } }, "SubTopicDistributionDto": { "type": "object", "properties": { "subTopicId": { "type": "integer", "format": "int32" }, "topicId": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "byStage": { "type": "array", "items": { "$ref": "#/components/schemas/StageCountDto" } }, "notPositioned": { "type": "integer", "description": "Enrolled partners without a current state in this subtopic.", "format": "int32" } } }, "SubTopicDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" } } }, "SurveyStatusDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "active": { "type": "boolean", "description": "Inactive surveys are hidden from partners but still count for completion." }, "responded": { "type": "boolean" }, "requiredAnswered": { "type": "integer", "format": "int32" }, "requiredTotal": { "type": "integer", "format": "int32" }, "complete": { "type": "boolean" } } }, "TopicDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "subTopics": { "type": "array", "items": { "$ref": "#/components/schemas/SubTopicDto" } } } }, "TransitionPartnerWorkDto": { "type": "object", "properties": { "partnerId": { "type": "integer", "format": "int32" }, "organizationName": { "type": "string" }, "complete": { "type": "boolean", "description": "True when this partner has completed the transition: every initiative at 100%, every survey's required questions answered and every signature signed. Uploads don't count." }, "initiatives": { "type": "array", "items": { "$ref": "#/components/schemas/InitiativeStatusDto" } }, "surveys": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyStatusDto" } }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureStatusDto" } }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/UploadStatusDto" } } } }, "TransitionWorkDto": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "place": { "$ref": "#/components/schemas/WorkItemPlaceDto" }, "enrolledPartners": { "type": "integer", "description": "Every count in rollup is out of this many partners; partners is a page of them.", "format": "int32" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItemDto" }, "description": "How the enrolled partners stand on each item of this transition." }, "partners": { "type": "array", "items": { "$ref": "#/components/schemas/TransitionPartnerWorkDto" } } }, "nullable": true }, "TrendPeriodDto": { "type": "object", "properties": { "start": { "type": "string", "description": "UTC. Weeks start on Monday, months on the 1st.", "format": "date-time" }, "end": { "type": "string", "description": "UTC, exclusive.", "format": "date-time" }, "positionChanges": { "type": "integer", "description": "Position changes (set or cleared).", "format": "int32" }, "advances": { "type": "integer", "description": "Position changes to a later stage.", "format": "int32" }, "setbacks": { "type": "integer", "description": "Position changes to an earlier stage.", "format": "int32" }, "activePartners": { "type": "integer", "description": "Partners with at least one event in the period.", "format": "int32" }, "initiativesCompleted": { "type": "integer", "description": "Initiatives that reached 100%.", "format": "int32" }, "kpiValuesReported": { "type": "integer", "format": "int32" }, "awardsGranted": { "type": "integer", "format": "int32" }, "partnersInvited": { "type": "integer", "format": "int32" }, "partnersJoined": { "type": "integer", "format": "int32" }, "partnersRemoved": { "type": "integer", "format": "int32" }, "positionsPerStage": { "type": "array", "items": { "$ref": "#/components/schemas/TrendStageCountDto" }, "description": "Positions (partner × subtopic) per stage at the end of the period, for the partners enrolled today, rebuilt from the history." }, "averageStageOrder": { "type": "number", "description": "Mean stage order of those positions; null when there are none.", "format": "double", "nullable": true } } }, "TrendStageCountDto": { "type": "object", "properties": { "stageId": { "type": "integer", "format": "int32" }, "positions": { "type": "integer", "format": "int32" } } }, "TrendStageDto": { "type": "object", "properties": { "stageId": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" } } }, "UploadStatusDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApiUploadStatus" }, "uploadedAt": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true } } }, "UserDetailDto": { "type": "object", "properties": { "pendingEmailAddress": { "type": "string", "description": "A new e-mail address waiting for confirmation. It replaces emailAddress when the user opens the link sent to it (valid 48 hours).", "nullable": true }, "id": { "type": "integer", "format": "int32" }, "fullName": { "type": "string" }, "emailAddress": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "registrationDate": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "enabled": { "type": "boolean" }, "jobTitle": { "type": "string", "nullable": true }, "lastAccessDate": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "isAdministrator": { "type": "boolean" }, "preferredLanguage": { "type": "string", "nullable": true } }, "nullable": true }, "UserInfoDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "fullName": { "type": "string" }, "emailAddress": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "registrationDate": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "enabled": { "type": "boolean" }, "jobTitle": { "type": "string", "nullable": true }, "lastAccessDate": { "type": "string", "description": "UTC.", "format": "date-time", "nullable": true }, "isAdministrator": { "type": "boolean" }, "preferredLanguage": { "type": "string", "nullable": true } } }, "UserInvitationRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 255, "minLength": 0, "type": "string" }, "fullName": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Optional. The user can change it when registering.", "nullable": true }, "dryRun": { "type": "boolean", "description": "Check the request and return what would happen, without changing anything or sending e-mails." } } }, "UserInvitationResultDto": { "type": "object", "properties": { "outcome": { "$ref": "#/components/schemas/ApiUserInvitationOutcome" }, "dryRun": { "type": "boolean" }, "userId": { "type": "integer", "description": "Null in a dry run that would create the user.", "format": "int32", "nullable": true }, "emailAddress": { "type": "string" }, "emailStatus": { "$ref": "#/components/schemas/ApiEmailStatus" } }, "nullable": true }, "UserUpdateDto": { "type": "object", "properties": { "fullName": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Ignored when empty.", "nullable": true }, "emailAddress": { "maxLength": 255, "minLength": 0, "type": "string", "description": "A different address doesn't change the login at once: a confirmation link is sent to the new address (valid 48 hours) and a notice to the current one. Until the link is opened, the new address shows as pendingEmailAddress. Empty, or the current address, changes nothing.", "nullable": true }, "phone": { "maxLength": 20, "minLength": 0, "type": "string", "description": "An empty string clears the phone number.", "nullable": true }, "jobTitle": { "maxLength": 50, "minLength": 0, "type": "string", "description": "An empty string clears the job title.", "nullable": true } } }, "WorkItemCountsDto": { "type": "object", "properties": { "initiatives": { "type": "integer", "format": "int32" }, "surveys": { "type": "integer", "format": "int32" }, "signatures": { "type": "integer", "format": "int32" }, "uploads": { "type": "integer", "format": "int32" } } }, "WorkItemDto": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ApiWorkItemType" }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "place": { "$ref": "#/components/schemas/WorkItemPlaceDto" }, "active": { "type": "boolean", "description": "Only a survey has this. An inactive survey is hidden from partners but still counts for completion.", "nullable": true }, "rollup": { "$ref": "#/components/schemas/WorkItemRollupDto" } } }, "WorkItemPlaceDto": { "type": "object", "properties": { "transitionId": { "type": "integer", "format": "int32" }, "subTopicId": { "type": "integer", "format": "int32" }, "subTopicName": { "type": "string" }, "topicId": { "type": "integer", "format": "int32" }, "topicName": { "type": "string" }, "fromStageName": { "type": "string", "description": "The stage a partner leaves." }, "toStageName": { "type": "string", "description": "The stage the transition leads to." } } }, "WorkItemRollupDto": { "type": "object", "properties": { "notStarted": { "type": "integer", "description": "Partners who have not started this item at all.", "format": "int32" }, "averageProgress": { "type": "number", "description": "Initiatives only: the mean progress over every enrolled partner, counting those who have not started as 0.", "format": "double", "nullable": true }, "started": { "type": "integer", "description": "Initiatives only: partners with progress above 0.", "format": "int32", "nullable": true }, "responded": { "type": "integer", "description": "Surveys only: partners who have answered at least one question.", "format": "int32", "nullable": true }, "uploaded": { "type": "integer", "description": "Uploads only: partners who have uploaded their file.", "format": "int32", "nullable": true }, "opened": { "type": "integer", "description": "Uploads only: partners who opened the request without uploading.", "format": "int32", "nullable": true }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Signatures only: how many partners are at each status.", "nullable": true }, "complete": { "type": "integer", "description": "Partners who have finished this item. Always absent for uploads, which never count towards completing a transition.", "format": "int32", "nullable": true } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Key identifier, shown in My Organization.", "name": "X-API-Key", "in": "header" }, "ApiSecret": { "type": "apiKey", "description": "Secret shown once, when the key was created.", "name": "X-API-Secret", "in": "header" } } }, "security": [ { "ApiKey": [ ], "ApiSecret": [ ] } ], "tags": [ { "name": "ActivityApi" }, { "name": "CustomerApi" }, { "name": "EnrollmentsApi" }, { "name": "KpisApi" }, { "name": "PartnersApi" }, { "name": "PositionsApi" }, { "name": "ProgramsApi" }, { "name": "ReportingApi" }, { "name": "UsersApi" } ] }