Details

openapi: 3.0.1 info: title: segments version: latest servers: - url: 'https://banno.com' tags: - name: JSON description: JSON API Segment Endpoints - name: CSV description: CSV Importing Endpoints paths: '/a/segments/api/v0/institutions/{institutionId}/segments': post: tags: - JSON summary: Create a segment. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' requestBody: description: SegmentPayload content: application/json: schema: $ref: '#/components/schemas/SegmentPayload' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Segment' '400': description: BadRequest '422': description: UnprocessableEntity '500': description: Internal server error deprecated: false get: summary: Retrieve a list of segments by institution. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] tags: - JSON parameters: - $ref: '#/components/parameters/institutionId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segments' '500': description: Internal server error. deprecated: false '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}': get: tags: - JSON summary: Retrieve a segment by ID. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segment' '404': description: NotFound '500': description: Internal server error. deprecated: false put: tags: - JSON summary: Update a segment by ID. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' requestBody: description: SegmentUpdatePayload content: application/json: schema: $ref: '#/components/schemas/SegmentUpdatePayload' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segment' '400': description: BadRequest '422': description: UnprocessableEntity '500': description: Internal server error. deprecated: false delete: tags: - JSON summary: Delete a segment by ID. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '204': description: NoContent '500': description: Internal server error. deprecated: false '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}/end-users.csv': get: tags: - CSV summary: Retrieve a csv containing all the users in a segment. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '200': description: Returns a content-disposition of a csv containing all the users within the segment. '404': description: NotFound '500': description: Internal server error. deprecated: false '/a/segmentation/api/v0/institutions/{institutionId}/history/permissions': post: tags: - JSON summary: Trigger a permissions history event with unsaved segment. security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' responses: '200': description: OK '400': description: BadRequest '404': description: NotFound '500': description: Internal server error. deprecated: false '/a/segmentation/api/v0/institutions/{institutionId}/segments/{segmentId}/history/permissions': post: tags: - JSON summary: Trigger a permissions history event with the provided segment. security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '200': description: OK '400': description: BadRequest '404': description: NotFound '500': description: Internal server error. deprecated: false '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}/stats': get: tags: - JSON summary: Return calculated information about a segment. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SegmentStatistics' '404': description: NotFound '500': description: Internal server error. '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}/end-users': get: summary: Retrieve a list of users for small segments having up to 150 users. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] tags: - JSON parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EndUsers' '400': description: BadRequest for segments with more than 150 users. For large segments, please utilize the CSV endpoint. '404': description: NotFound '500': description: Internal server error. '/a/segments/api/v0/institutions/{institutionId}/drafts/{draftId}': get: tags: - JSON summary: Retrieve a drafted segment. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/draftId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DraftedSegment' '400': description: BadRequest '500': description: Internal server error deprecated: false '/a/segments/api/v0/institutions/{institutionId}/drafts/{draftId}/missing-users.csv': get: tags: - CSV summary: Retrieve a csv containing all the not-found users of a drafted segment. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/draftId' - $ref: '#/components/parameters/institutionId' responses: '200': description: Returns a content-disposition of the csv file containing all not-found users. '400': description: BadRequest '500': description: Internal server error deprecated: false '/a/segments/api/v0/institutions/{institutionId}/drafts/{draftId}/end-user-ids.csv': get: tags: - CSV summary: Retrieve a csv containing all the end user ids tied to a drafted segment. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/draftId' - $ref: '#/components/parameters/institutionId' responses: '200': description: Returns a content-disposition of the csv file containing all draft users. '400': description: BadRequest '500': description: Internal server error deprecated: false '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}/drafts/{draftId}': post: tags: - JSON summary: Replace all users in a segment. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' - $ref: '#/components/parameters/draftId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segment' '404': description: NotFound '500': description: Internal server error. put: tags: - JSON summary: Append users to a segment. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - name: segmentId in: path required: true schema: type: string format: UUID description: Unique ID of the Segment. - name: draftId in: path required: true schema: type: string format: UUID description: Unique ID of the Drafted Segment. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segment' '404': description: NotFound '500': description: Internal server error. delete: tags: - JSON summary: Delete matching users in a segment. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' - $ref: '#/components/parameters/draftId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segment' '404': description: NotFound '500': description: Internal server error. '/a/segments/api/v0/institutions/{institutionId}/end-users/{endUserId}/segments': get: summary: Retrieve a list of segments by end-user. description: Requires the "View digital banking ads" permission security: - clientCredentials: [] tags: - JSON parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/endUserId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Segments' '500': description: Internal server error. deprecated: false '/a/segments/api/v0/institutions/{institutionId}/import': post: summary: Parse CSV file containing Users. description: Requires the "Edit digital banking ads" permission security: - clientCredentials: [] tags: - CSV parameters: - $ref: '#/components/parameters/institutionId' - name: sourceType in: query description: The source type for the csv to be parsed. Accepted values - netteller-ids, member-numbers, usernames, and userIds. required: true schema: type: string enum: [netteller_id, member_number, username, userId] requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/EndUsersCSVForm' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParsedCSVResults' '400': description: BadRequest '500': description: Internal server error deprecated: false '/a/segments/api/v0/institutions/{institutionId}/segments/{segmentId}/import': post: summary: Parse CSV file containing users in order to perform an operation on segment end-users. description: Requires the "Edit digital banking ads" permission tags: - CSV parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/segmentId' - name: sourceType in: query description: The source type for the csv to be parsed. required: true schema: type: string enum: [netteller_id, member_number, username, userId] - name: operationType in: query description: The operation type that will be performed with the csv being uploaded. required: true schema: type: string enum: [append, delete] requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/EndUsersCSVForm' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParsedCSVResults' '400': description: BadRequest '500': description: Internal server error deprecated: false components: securitySchemes: clientCredentials: type: oauth2 description: OAuth2 using the client credentials flow flows: clientCredentials: tokenUrl: https://banno.com/a/oidc-provider/api/v0/token scopes: {} parameters: institutionId: name: institutionId in: path description: The Unique ID of the institution. required: true schema: type: string format: UUID endUserId: name: endUserId in: path required: true description: Unique ID of the User. schema: type: string format: UUID segmentId: name: segmentId in: path required: true description: Unique ID of the Segment. schema: type: string format: UUID draftId: name: draftId in: path required: true description: Unique ID of the Drafted Segment. schema: type: string format: UUID schemas: SegmentPayload: required: - name - sourceProvider - draftId type: object properties: name: type: string description: The name of the Segment. sourceProvider: type: string description: The entity providing the csv for the segment. (The FI, Banno, Geezeo, etc.) draftId: type: string format: UUID description: The id of the draft to be used to create the segment. SegmentUpdatePayload: required: - name - sourceProvider type: object properties: name: type: string description: The name of the Segment. sourceProvider: type: string description: The entity providing the csv for the segment. (The FI, Banno, Geezeo, etc.) Segment: required: - createdAt - institutionId - name - segmentId - updatedAt - sourceProvider type: object properties: name: type: string description: The name of the segment. updatedAt: type: string format: date-time description: The date and time that a segment was last updated. segmentId: type: string format: UUID description: The UUID associated with the requested segment. institutionId: type: string format: UUID description: Unique ID of the Institution. draftId: type: string format: UUID description: Optional unique ID of the draft used to create this segment's users list. createdAt: type: string format: date-time description: The date and time that a segment was created. sourceProvider: type: string description: The entity providing the csv for the segment. (The FI, Banno, Geezeo, etc.) DraftedSegment: required: - draftId - institutionId - createdAt type: object properties: draftId: type: string format: UUID institutionId: type: string format: UUID createdAt: type: string format: date-time Segments: required: - segments type: object properties: segments: type: array items: $ref: '#/components/schemas/Segment' EndUser: required: - endUserId - firstName - lastName - username type: object properties: email: type: string username: type: string rowNumber: type: integer format: int32 nettellerId: type: string lastName: type: string firstName: type: string endUserId: type: string format: UUID memberNumber: type: string EndUsers: required: - endUsers type: object properties: endUsers: type: array items: $ref: '#/components/schemas/EndUser' EndUsersCSVForm: type: object properties: sourceProvider: type: string description: The entity providing the csv for the segment. (The FI, Banno, Geezeo, etc.) file: type: object description: CSV file of end user identifiers user_identifier_csv_column: type: integer description: >- optional column index in csv corresponding to end user identifier values (defaulting of zero) csv_header_row_exists: type: boolean description: >- optional flag to specify if the csv's first row are headers (defaulting to true) ParsedCSVResults: required: - csvHeaders - csvUnknownRows - draftId - foundUsersCount type: object properties: csvHeaders: type: array items: type: string description: An array containing the headers provided by the parsed csv. csvUnknownRows: type: array items: $ref: '#/components/schemas/CsvUnknownRow' description: An Array of all the users that were not found during parsing. draftId: type: string format: UUID description: The UUID given to the drafted segment. foundUsersCount: type: integer format: int32 description: The number of found users. CsvUnknownRow: required: - rowNumber - values type: object properties: rowNumber: type: integer format: int32 description: The csv row number associated with the not-found user. values: type: array items: type: string description: An array of each column value associated with the not-found user. description: CsvUnknownRow SegmentStatistics: required: - numberOfCampaigns - userCount type: object properties: numberOfCampaigns: type: integer format: int32 description: The number of campaigns the segment is included in. userCount: type: integer format: int32 description: The number of users in the segment.