FINOS Users API
The Users API from FINOS — 6 operation(s) for users.
OpenAPI Specification
openapi: 3.0.1
info:
title: Agent Admin Users API
description: 'This document refers to Symphony API calls to send and receive messages
and content. They need the on-premise Agent installed to perform
decryption/encryption of content.
- sessionToken and keyManagerToken can be obtained by calling the
authenticationAPI on the symphony back end and the key manager
respectively. Refer to the methods described in authenticatorAPI.yaml.
- Actions are defined to be atomic, ie will succeed in their entirety
or fail and have changed nothing.
- If it returns a 40X status then it will have sent no message to any
stream even if a request to some subset of the requested streams
would have succeeded.
- If this contract cannot be met for any reason then this is an error
and the response code will be 50X.
- MessageML is a markup language for messages. See reference here:
https://rest-api.symphony.com/docs/messagemlv2
- **Real Time Events**: The following events are returned when reading
from a real time messages and events stream ("datafeed"). These
events will be returned for datafeeds created with the v5 endpoints.
To know more about the endpoints, refer to Create Messages/Events
Stream and Read Messages/Events Stream. Unless otherwise specified,
all events were added in 1.46.
'
version: 25.8.1
servers:
- url: youragentURL.symphony.com/agent
tags:
- name: Users
paths:
/v2/user:
get:
summary: Get user information
produces:
- application/json
parameters:
- name: uid
description: User ID as a decimal integer
in: query
required: false
type: integer
format: int64
- name: email
description: Email address
in: query
required: false
type: string
format: email
- name: username
description: login user name
in: query
required: false
type: string
- name: local
description: 'If true then a local DB search will be performed and only local pod users will be
returned. If absent or false then a directory search will be performed and users
from other pods who are visible to the calling user will also be returned.
Note: for username search, the local flag must be true
'
in: query
required: false
type: boolean
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/UserV2'
'204':
description: No user found.
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v3/users:
get:
summary: 'Search users by emails or ids.
Only one of the search lists should be informed at a time.
Search lists may containt up to 100 elements.
'
produces:
- application/json
parameters:
- name: uid
description: User IDs as a list of decimal integers separated by comma
in: query
required: false
type: string
- name: email
description: List of email addresses separated by comma
in: query
required: false
type: string
- name: username
description: List of username separated by comma
in: query
required: false
type: string
- name: local
description: 'If true then a local DB search will be performed and only local pod users will be
returned. If absent or false then a directory search will be performed and users
from other pods who are visible to the calling user will also be returned.
'
in: query
required: false
type: boolean
- name: active
description: 'If not set all user status will be returned,
if true all active users will be returned,
if false all inactive users will be returned
'
in: query
required: false
type: boolean
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2UserList'
examples:
application/json:
users:
- id: 15942919536460
emailAddress: technicalwriter@symphony.com
firstName: Technical
lastName: Writer
displayName: Technical Writer
title: Technical Writer
company: Symphony
department: Marketing // if internal user
username: tw
accountType: NORMAL
location: France // if internal user
avatars:
- size: original
url: ../avatars/static/150/default.png
- size: small
url: ../avatars/static/50/default.png
- id: 15942919536461
emailAddress: serviceaccount@symphony.com
firstName: null
lastName: null
displayName: Service Account
title: null
company: pod232
department: Marketing // if internal user
username: SA
location: France // if internal user
accountType: SYSTEM
avatars:
- size: original
url: ../avatars/static/150/default.png
- size: small
url: ../avatars/static/50/default.png
errors:
- error: invalid.format
email: notavalidemail
- error: invalid.format
id: 654321
'204':
description: No user found.
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
/v1/users/{uid}/sessions/{sid}/logout:
post:
summary: 'Ends the session identified by {sid} for the user with the identifier {uid}.
'
produces:
- application/json
parameters:
- name: uid
description: The identifier of the user who owns the session to be terminated.
in: path
required: true
type: string
- name: sid
description: The identifier of the session to be terminated.
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/SuccessResponse'
'400':
description: Client error.
schema:
$ref: '#/definitions/Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
schema:
$ref: '#/definitions/Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/v1/users/{uid}/sessions/logout:
post:
summary: 'Ends all sessions for the user identified by {uid}.
'
produces:
- application/json
parameters:
- name: uid
description: The identifier of the user whose sessions are to be terminated.
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/SuccessResponse'
'400':
description: Client error.
schema:
$ref: '#/definitions/Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
schema:
$ref: '#/definitions/Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/v1/users/{uid}/sessions:
get:
summary: 'Lists all sessions for the user identified by {uid}.
'
produces:
- application/json
parameters:
- name: uid
description: The identifier of the user whose sessions are to be listed.
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V1UserSessions'
'204':
description: No user found.
'400':
description: Client error.
schema:
$ref: '#/definitions/Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
schema:
$ref: '#/definitions/Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/v1/user/search:
post:
summary: Search for users by name or email address
consumes:
- application/json
produces:
- application/json
parameters:
- name: skip
description: number of records to skip
in: query
type: integer
- name: limit
description: Max number of records to return. If no value is provided, 50 is the default.
in: query
type: integer
- name: local
description: 'If true then a local DB search will be performed and only local pod users will be
returned. If absent or false then a directory search will be performed and users
from other pods who are visible to the calling user will also be returned.
'
in: query
required: false
type: boolean
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: searchRequest
description: search criteria
in: body
required: true
schema:
$ref: '#/definitions/UserSearchQuery'
tags:
- Users
responses:
'200':
description: OK
schema:
$ref: '#/definitions/UserSearchResults'
examples:
application/json:
count: 1
skip: 0
limit: 1
searchQuery:
query: jane
filters:
title: Sales Manager
company: Symphony
location: San Francisco
marketCoverage: EMEA
responsibility: BAU
function: Trade Management
instrument: Securities
accountTypes:
- NORMAL
users:
- id: 13056700581099
emailAddress: janedoe@symphony.com
firstName: Jane
lastName: Doe
displayName: Jane Doe
title: Sales Manager
company: Symphony
location: San Francisco
accountType: NORMAL
avatars:
- size: original
url: ../avatars/static/150/default.png
- size: small
url: ../avatars/static/50/default.png
'204':
description: No user found.
'400':
description: Client error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
definitions:
UserSearchQuery:
type: object
properties:
query:
type: string
description: search / query term. This can be firstname, lastname, displayname or email
example: jane
filters:
$ref: '#/definitions/UserSearchFilter'
UserSearchResults:
type: object
properties:
count:
description: The total number of users which matched the search criteria.
type: integer
format: int64
example: 1
skip:
description: The number of skipped results.
type: integer
format: int64
example: 0
limit:
description: The number of returned results.
type: integer
format: int64
example: 1
searchQuery:
$ref: '#/definitions/UserSearchQuery'
users:
description: A list of users which matched by the search criteria.
type: array
items:
$ref: '#/definitions/UserV2'
example:
- null
UserV2:
description: User record version 2
type: object
properties:
id:
type: integer
format: int64
example: 7696581394433
emailAddress:
type: string
format: email
example: admin@symphony.com
firstName:
type: string
example: Symphony
lastName:
type: string
example: Admin
displayName:
type: string
example: Symphony Admin
title:
type: string
example: Administrator
company:
type: string
example: Acme
username:
type: string
example: admin@symphony.com
location:
type: string
example: California
accountType:
type: string
enum:
- NORMAL
- SYSTEM
- SDL
example: NORMAL
avatars:
$ref: '#/definitions/AvatarList'
workPhoneNumber:
type: string
description: 'Note: only available if the application has the extended user or contact permission'
example: '+33901020304'
mobilePhoneNumber:
type: string
description: 'Note: only available if the application has the extended user or contact permission'
example: '+33601020304'
jobFunction:
type: string
description: 'Note: only available if the application has the extended user or contact permission'
example: Sales
department:
type: string
description: 'Note: only available if the application has the extended user or contact permission'
example: APIs
division:
type: string
description: 'Note: only available if the application has the extended user or contact permission'
example: Partnerships
roles:
$ref: '#/definitions/StringList'
example:
- INDIVIDUAL
- SUPER_ADMINISTRATOR
userMetadata:
type: object
description: Metadata map of key/values
additionalProperties:
type: object
example:
com_symphony_metadataKey1: value
com_symphony_metadataKey2:
- value1
- value2
Avatar:
type: object
properties:
size:
description: The Avatar Size
type: string
example: original
url:
description: Url of the image
type: string
example: ../avatars/izcQTdRVFOK_qhCrYeQOpIuHKuZuMk3J88Uz_bShzM8.png
SuccessResponse:
type: object
properties:
format:
type: string
enum:
- TEXT
- XML
example: TEXT
message:
type: string
example: Success
AvatarList:
type: array
items:
$ref: '#/definitions/Avatar'
example:
- size: original
url: ../avatars/izcQTdRVFOK_qhCrYeQOpIuHKuZuMk3J88Uz_bShzM8.png
- size: small
url: ../avatars/izcQTdRVFOK_qhCrYeQOpIuHKuZuMk3J88Uz_bShzM8_small.png
V1Session:
description: V1 Detailed Session record.
type: object
properties:
sessionId:
type: string
description: The id of the user session
clientIp:
type: string
description: The ip address of the session initiator
userId:
type: integer
format: int64
description: The user id of the session initiator
userAgent:
type: string
description: The user agent of the session
browser:
type: string
description: The browser section of the user agent
os:
type: string
description: The os section of the user agent
device:
type: string
description: The device section of the user agent
deviceHash:
type: string
description: A hash uniquely identifying the device of the requester
creationTime:
type: integer
format: int64
description: The timestamp of the creation time the user session
expirationDelay:
type: integer
format: int64
description: The timestamp of the expiry time of the user session
StringList:
type: array
items:
type: string
example:
- ftp
- mailto
- fdsup
- skype
V1UserSessions:
description: V1 Detailed Sessions Record.
type: object
properties:
sessions:
type: array
items:
$ref: '#/definitions/V1Session'
UserSearchFilter:
type: object
properties:
accountTypes:
$ref: '#/definitions/StringList'
description: type of user used to search
example: NORMAL
title:
type: string
description: user's job title
example: Sales Manager
company:
type: string
description: company name
example: Symphony
location:
type: string
description: city of the user's job location
example: Marseille
marketCoverage:
type: string
description: geographic area the user works with
example: EMEA
responsibility:
type: string
description: user's responsibility
example: BAU
function:
type: string
description: user's function
example: Trade Management
instrument:
type: string
description: higher level instrument for the Asset Classes
example: Securities
UserError:
description: User error information
type: object
properties:
error:
type: string
description: Error code informing what is wrong
example: invalid.format
email:
type: string
description: 'Email with error. Only one of the following fields should be present: email or id'
example: notavalidemail
id:
type: string
description: 'Id with error. Only one of the following fields should be present: email or id'
example: notavalidid
V2UserList:
description: List of User record version 2
type: object
properties:
users:
type: array
items:
$ref: '#/definitions/UserV2'
description: List of all users found with the search
example:
- id: 15942919536460
emailAddress: technicalwriter@symphony.com
firstName: Technical
lastName: Writer
displayName: Technical Writer
title: Technical Writer
company: Symphony
department: Marketing // if internal user
username: tw
accountType: NORMAL
location: France // if internal user
mobilePhoneNumber: 33601020304
avatars:
- size: original
url: ../avatars/static/150/default.png
- size: small
url: ../avatars/static/50/default.png
- id: 15942919536461
emailAddress: serviceaccount@symphony.com
firstName: null
lastName: null
displayName: Service Account
title: null
company: pod232
department: Marketing // if internal user
username: SA
location: France // if internal user
accountType: SYSTEM
avatars:
- size: original
url: ../avatars/static/150/default.png
- size: small
url: ../avatars/static/50/default.png
errors:
type: array
items:
$ref: '#/definitions/UserError'
description: List of all errors found with the informed search criteria
example:
- error: invalid.format
email: notavalidemail
- error: invalid.format
id: 654321
Error:
type: object
properties:
code:
type: integer
format: int32
example: 401
message:
type: string
example: Invalid session