REST Web services

From Cyclos 3.7, some REST services are supported, using messages formatted as JSON.

They are not just a different format than the SOAP web services, but also a different approach. In Cyclos, SOAP web services require a web service client to be configured (through the Settings menu), which will allow access to an specific IP address and have a separate set of permissions. The REST services, in the other hand, don't control access by IP address, but require an specific member to be authenticated. The services will use the same permissions as that member would have in Cyclos web application (except that the payment types need to be enabled for the rest channel). Those services use a specific rest channel, which needs to be enabled for groups, and individually per member, on the external access page.

The original use case for the REST services is the mobile application, where a member logs in the application and performs operations directly on Cyclos. The REST api was chosen because it is easier for the mobile application than SOAP. However, there is no limitation of which application can use the REST services.

General guidelines

Response bodies contains JSON objects. However, it is always good to check the response's Content-type header, as under some errors a distinct response format may be returned (for example, invalid URL or HTTP method can return a regular server error page).
Raw dates are normally formatted using the ISO 8601 format.
To reduce textual output, empty properties on objects, as well as empty arrays are suppressed from the generated JSON string.
The property order on objects is not guaranteed. Anyway, clients shouldn't rely on it.
In all services which require a request body object, the following header is required:

Content-Type: application/json

All service URLs, except for <cyclos>/rest/general, require an authenticated user. This is done through the regular HTTP Basic authentication, which is sent as a request header:

Authorization: Basic <Base64 encoding of username:password>

Services that require a post body object also expect it to be JSON encoded.
Handled exceptions also return Content-type: application/json, with an object containing the following properties:
- error: An error code which can be relied on to find out what caused the problem. Common codes are:
  - NOT_FOUND: An expected data was not found, normally from input identifiers. The details property will contain which data type was not found. Examples are MEMBER, ACCOUNT, TRANSFER, etc.
  - INVALID_ARGUMENT: Some request argument was not of the expected type.
  - PERMISSION_DENIED: Attempt to perform an operation which has been denied by lacking permission for it.
  - INTERNAL_SERVER_ERROR: General, unexpected error. On the server side, a log should be generated with the complete error trace.
  - INACTIVE_TRANSACTION_PASSWORD: If transaction password is required and the authenticated user's transaction password is not active.
  - MISSING_TRANSACTION_PASSWORD: If transaction password is required to perform some operation (like performing a payment) and it was not informed.
  - INVALID_TRANSACTION_PASSWORD: A given transaction password is invalid.
  - BLOCKED_TRANSACTION_PASSWORD: A given transaction password has been blocked by exceeding the maximum allowed tries.
- details: Optional details about the specific error type.

Available services

The REST services are available under the url <cyclos_root>/rest/. The following services are available:

General

Used to access general information about the server. Does not require authentication

Service	URI	HTTP method	Input	Result
Get general information about the Cyclos server	general	GET	none	Object: cyclosVersion: The Cyclos version deployed on the server applicationName: The application name configured on the server principalType: The principal (user authentication) used to identify users, as configured on the REST channel. Possible values: USER: Login name EMAIL: E-mail CARD: Card number CUSTOM_FIELD: An unique custom field. In this case, the specific custom field is returned on the principalCustomField property principalCustomField: Only used if principalType is CUSTOM_FIELD. Contains details on which custom field is used. Same object as member custom field. credentialType: The credential used by the REST channel. May be one of the following: LOGIN_PASSWORD: Uses only the login password to authenticate. TRANSACTION_PASSWORD: Uses only the transaction password to authenticate. PIN: Uses only the pin to authenticate. CARD_SECURITY_CODE: Uses only the card security code to authenticate. Only possible if principalType is CARD. images: A list of image objects, as in Get the authenticated member's profile. By now, only mobile splash images. The caption attribute of the image object is not returned since it doesn't apply for this cases.

Access

Used to access general information about the authenticated user

Service	URI	HTTP method	Input	Result
Get commonly used data for a client-side application	access/initialData	GET	none	Object: profile: The authenticated user profile. Same object as getting the authenticated user profile requireTransactionPassword: Flag used when the transaction password is needed for sensitive operations. accounts: Array of all user accounts. Same objects as get user accounts canMakeMemberPayments: Flag that indicates if the member can make a payment to other member. canMakeSystemPayments: Flag that indicates if the member can make a payment to system. decimalCount: The number of decimal places used for normal precision. decimalSeparator: Decimal number separator.

Members

Allows returning and updating the authenticated member's profile, as well as searching for other members.

Service	URI	HTTP method	Input	Result
Get the authenticated member's profile	members/me	GET	none	Object: id: The internal, numerical identifier name: The full name username: The login name email: The e-mail customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id displayName: The custom field display name value: The custom field value hiddenFields: An array containing the internal names of custom fields currently hidden for others images: An array containing objects, each describing an image, with the following properties: id: The internal, numerical identifier caption: The member-assigned caption for the image thumbnailUrl: The URL for accessing the image thumbnail fullUrl: The URL for accessing the full image lastModified: The last modification date.
Update the authenticated member's profile	members/me	POST	Object on the request body: name: The full name username: The login name email: The e-mail customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id possibleValueId: The custom field possible value id value: The custom field value hidden: A boolean flag indicating whether the field value is hidden The field of a custom field value can be identified passing the internal name (internalName) or field id (fieldId). If the value of a custom field value is an enumerated value it is sufficient to pass the possible value id (possibleValueId), or the enumerated string value in the value parameter.	none
Get an specific member's profile information, finding the member by id	members/<id>	GET	Path variable id: the desired member's numeric identifier	Object: id: The internal, numerical identifier name: The full name username: The login name email: The e-mail customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id displayName: The custom field display name value: The custom field value images: An array containing objects, each describing an image, with the following properties: id: The internal, numerical identifier caption: The member-assigned caption for the image thumbnailUrl: The URL for accessing the image thumbnail fullUrl: The URL for accessing the full image
Get an specific member's profile information, finding the member by the principal configured on the rest channel (username, custom field, e-mail, etc)	members/principal/<principal>	GET	Path variable principal: the desired member's principal	Same object as load member by id
Search members using custom criteria	members	GET	Query parameters: currentPage: Number indicating the current result page, starting with 0 (the default) pageSize: Amount of results returned. 10 by default, 100 max. keywords: String used to match name, username, e-mail and custom fields in a full-text search. withImagesOnly: If set to true, returns only members which have at least one image. Accepts true / false. False by default. showCustomFields: Indicates whether the results should include custom field values. Accepts true / false. False by default. showImages: Indicates whether the results should include images. Accepts true / false. False by default. excludeLoggedIn: Indicates whether to exclude the logged user from results. Accepts true / false. False by default. customValue.<fieldInternalName>: Value for a custom field filter for a given field by internal name. Only works for custom fields marked for search. In case the custom field has an enumerated type, the id of a possible value should be entered here.	Object: currentPage: Number indicating the actual returned page, starting with 0 totalCount: Number indicating the total count of matched results elements: Array containing the same objects as load member by id, except that customValues and images will only be filled if showCustomFields and showImages, respectively, were requested with true values.
Gets details of an specific member and the member custom fields	members/memberData/<id>	GET	Path variable id: The desired member id	An object that contains the following information: canAddMemberAsContact: Indicates if member can be added to the contact list. member: Same object as load member by id

Member custom fields

Allows getting information on member custom fields

Service	URI	HTTP method	Input	Result
Get details of a custom field by id	memberFields/<id>	GET	Path variable id: numeric identifier	Object: id: The internal, numerical identifier displayName: The custom field display name internalName: The custom field internal name type: The custom field type. May be one of the following: STRING, ENUMERATED, INTEGER, DECIMAL, DATE, BOOLEAN or URL control: The form control used to input values for that custom field. May be one of the following: TEXT, TEXTAREA, RICH_EDITOR, SELECT, RADIO or CHECKBOX required: Boolean flag indicating whether the field is required mask: The mask used for inputting / formatting field values. Only makes sense if type is STRING. parentFieldId: Number containing the numeric identifier of this field's parent field. Only makes sense if type is ENUMERATED. possibleValues: An array of the same object as getting the possible values of a field by id. maxLength: The field maximum length. minLength: The field minimum length.
Get details of a custom field by internal name	memberFields/name/<internalName>	GET	Path variable internalName: custom field internal name	Same object as returning a custom field by id.
List all member custom fields used for the currently authenticated user	memberFields/mine	GET	none	Array of the same objects as returning a custom field by id.
List all member custom fields used for an specific member, finding the member by the internal identifier	memberFields/byMemberId/<id>	GET	Path variable id: the desired member's id	Array of the same objects as returning a custom field by id.
List all member custom fields used for an specific member, finding the member by the principal configured on the rest channel (username, custom field, e-mail, etc)	memberFields/byMemberPrincipal/<principal>	GET	Path variable principal: the desired member's principal	Array of the same objects as returning a custom field by id.
List all member custom fields which may be used to search members	memberFields/forSearch	GET	none	Array of the same objects as returning a custom field by id.
List all member custom fields which may be used to search advertisements	memberFields/forAdsSearch	GET	none	Array of the same objects as returning a custom field by id.
List the possible values of an enumerated custom field, finding the custom field by id, optionally filtering by parent value id	memberFields/<id>/possibleValues[/<parentId>]	GET	Path variable id: the desired custom field's id Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of objects: id: The numeric identifier value: The possible value
List the possible values of an enumerated custom field, finding the custom field by internal name, optionally filtering by parent value id	memberFields/name/<name>/possibleValues[/<parentId>]	GET	Path variable name: the desired custom field's internal name Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of the same objects as getting the possible values of a field by id.

Contacts

Provides access to the authenticated user contact list

Service	URI	HTTP method	Input	Result
Get a contact by id	contacts/<id>	GET	Path variable id: the contact numeric identifier	Object: id: The internal, numerical identifier member: Same object as get member by id notes: Text containing personal notes about this contact.
Get all contacts	contacts	GET	none	Array of the same objects as get contact by id
Get a contact by member id	contacts/byMemberId/<id>	GET	Path variable id: the member numeric identifier	Same object as get contact by id
Get a contact by member principal (username, custom field, e-mail, etc, as configured on the rest channel)	contacts/byMemberPrincipal/<principal>	GET	Path variable principal: the member principal	Same object as get contact by id
Save a contact by member id	contacts/byMemberId/<id>	POST	Path variable id: the member numeric identifier Optional request body object containing the following properties: notes: Text containing personal notes about this contact.	Same object as get contact by id
Save a contact by member principal (username, custom field, e-mail, etc, as configured on the rest channel)	contacts/byMemberPrincipal/<principal>	POST	Path variable principal: the member principal Optional request body object containing the following properties: notes: Text containing personal notes about this contact.	Same object as get contact by id
Remove a contact by id	contacts/<id>	DELETE	Path variable id: the contact numeric identifier	none
Remove a contact by member id	contacts/byMemberId/<id>	DELETE	Path variable id: the member numeric identifier	none
Remove a contact by member principal (username, custom field, e-mail, etc, as configured on the rest channel)	contacts/byMemberPrincipal/<principal>	DELETE	Path variable principal: the member principal	none

Accounts

Provides access to data about the authenticated user's accounts

Service	URI	HTTP method	Input	Result
Get an account details by id	accounts/<id>	GET	Path variable id: the account numeric identifier	Object: id: The internal, numerical identifier default: Boolean flag indicating whether this is the authenticated user's default account type: Object representing the account type. Contains the following properties: id: The internal, numerical identifier name: The account type name currency: Object representing the account currency. Contains the following properties: id: The internal, numerical identifier name: The currency name symbol: The currency symbol
Get all account details	accounts	GET	none	Array of the same objects as get account by id
Get all accounts with their status	accounts/info	GET	none	A list of objects with the following properties: account: Same object as get account by id status: Same object as get status for specific account
Get the default account details	accounts/default	GET	none	Same object as get account by id
Get an account status by id	accounts/<id>/status	GET	Path variable id: the account numeric identifier	Object: balance: The raw numeric balance formattedBalance: The raw balance, formatted according to Cyclos's settings reservedAmount: The reserved amount for future debts formattedReservedAmount: The reserved amount, formatted according to Cyclos's settings availableBalance: The numeric available balance (balance - reservedAmount + creditLimit) formattedAvailableBalance: The available balance, formatted according to Cyclos's settings creditLimit: The numeric credit limit (how much an account can go below zero) formattedCreditLimit: The credit limit, formatted according to Cyclos's settings upperCreditLimit: The numeric upper credit limit (the maximim balance an account can get) formattedUpperCreditLimit: The upper credit limit, formatted according to Cyclos's settings
Get the default account status	accounts/default/status	GET	none	Same object as get status for specific account:
Gets details of an specific transfer	accounts/transferData/<id>	GET	Path variable id: The desired transfer id	An object that contains the following information: canAddRelatedMemberAsContact: Indicates if the related member can be added to the contact list. accountHistoryTransfer: Same object as get details of an specific transfer
Gets details of an specific transfer	accounts/transfer/<id>	GET	Path variable id: The desired transfer id	Object: id: The internal, numerical identifier date: ISO 8601 formatted transfer submission date formattedDate: The transfer submission date formatted according to Cyclos' configuration processDate: ISO 8601 formatted transfer processing date formattedProcessDate: The transfer processing date formatted according to Cyclos' configuration amount: Numeric transfer amount. Negative for outgoing, positive for incoming payments formattedAmount: Transfer amount formatted according to Cyclos' configuration transferType: Object containing the transfer type, with the following properties: id: The internal, numerical identifier name: The transfer type name member: Related member. May be null in payments from / to a system account systemAccountName: Related system account name, if a payment from / to a system account transactionNumber: The human-readable transaction number, if configured in Cyclos description: The textual description for this payment customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id displayName: The custom field display name value: The custom field value
Search for account history of an specific account	accounts/<id>/history	GET	Path variable id: The desired account id Query parameters: currentPage: Number indicating the current result page, starting with 0 (the default) pageSize: Amount of results returned. 10 by default, 100 max. showStatus: A boolean flag indicating whether the account status will also be returned on the result paymentFilterId: Numeric identifier for a payment filter. memberId: Numeric identifier for a related member memberPrincipal: Principal (username, e-mail, custom field, depending on what is configured on the rest channel) for a related member beginDate: Date filter for transfers, returning transfers with date greater or equals the given date. The date is formatted as ISO 8601 (yyyy-mm-ddThh:mm:ss) endDate: Date filter for transfers, returning transfers with date less or equals the given date. The date is formatted as ISO 8601 (yyyy-mm-ddThh:mm:ss) customValue.<fieldInternalName>: Filters returned transfers by a custom field value. Only works for custom fields marked to be used on search	An object with the following properties: currentPage: Number indicating the actual returned page, starting with 0 totalCount: Number indicating the total count of matched results elements: Array containing the same objects as get transfer by id status: Same object as get status for specific account, but will only be returned if requested with showStatus=true
Search for account history of the default account	accounts/default/history	GET	Same query parameters as account history for an specific account	The same result object as account history for an specific account
Gets details of an specific scheduled payment	accounts/scheduledPayment/<id>	GET	Path variable id: The desired transfer id	Object: id: The internal, numerical identifier date: ISO 8601 formatted transfer submission date formattedDate: The transfer submission date formatted according to Cyclos' configuration processDate: ISO 8601 formatted transfer processing date formattedProcessDate: The transfer processing date formatted according to Cyclos' configuration amount: Numeric transfer amount. Negative for outgoing, positive for incoming payments formattedAmount: Transfer amount formatted according to Cyclos' configuration transferType: Object containing the transfer type, with the following properties: id: The internal, numerical identifier name: The transfer type name member: Related member open: Boolean flag indicating whether the scheduled payment is still open description: The textual description for this payment customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id displayName: The custom field display name value: The custom field value installments: Array of objects with the following properties: id: The internal, numerical identifier date: ISO 8601 formatted installment due date formattedDate: The installment due date formatted according to Cyclos' configuration processDate: ISO 8601 formatted installment processing date formattedProcessDate: The installment processing date formatted according to Cyclos' configuration amount: Numeric installment amount. Negative for outgoing, positive for incoming payments formattedAmount: Installment amount formatted according to Cyclos' configuration status: Installment status. May be one of the following strings: PROCESSED: Installment successfully processed PENDING: Installment pending authorization DENIED: Installment authorization denied CANCELED: Installment cancelled by payer before being authorized / denied SCHEDULED: Installment still scheduled for a future date FAILED: Installment couldn't be processed at due date, for example, there where not enough funds for that BLOCKED: Installment blocked to prevent automatic processing at due date
Search for scheduled payments on an specific account	accounts/<id>/scheduledPayments	GET	Path variable id: The desired account id Query parameters: currentPage: Number indicating the current result page, starting with 0 (the default) pageSize: Amount of results returned. 10 by default, 100 max. memberId: Numeric identifier for a related member memberPrincipal: Principal (username, e-mail, custom field, depending on what is configured on the rest channel) for a related member beginDate: Date filter for transfers, returning transfers with date greater or equals the given date. The date is formatted as ISO 8601 (yyyy-mm-ddThh:mm:ss) endDate: Date filter for transfers, returning transfers with date less or equals the given date. The date is formatted as ISO 8601 (yyyy-mm-ddThh:mm:ss) incoming: Boolean flag indicating whether incoming (when true) or outgoing scheduled payments (false) will be returned. Defaults to false. status: Status for returned scheduled payments. May be one of the following strings: OPEN: Returns scheduled payments with at least one open installment. This is the default. CLOSED_WITHOUT_ERRORS: Returns scheduled payments where all installments are closed without errors. CLOSED_WITH_ERRORS: Returns scheduled payments which are closed and have at least one failed installment.	An object with the following properties: currentPage: Number indicating the actual returned page, starting with 0 totalCount: Number indicating the total count of matched results elements: Array containing the same objects as get scheduled payment by id
Search for scheduled payments on the default account	accounts/default/scheduledPayments	GET	Same query parameters as scheduledPayments for an specific account	The same result object as search scheduled payments for an specific account
List available payment filters for an specific account	accounts/<id>/paymentFilters	GET	Path variable id: The desired account id	A list of the same objects with the following properties: id: The internal, numerical identifier name: The payment filter name
List available payment filters for the default account	accounts/default/paymentFilters	GET	none	A list of the same objects as list payment filters for an specific account

Transfer types

Allows getting data about transfer types, which are used to perform payments

Service	URI	HTTP method	Input	Result
Get a transfer type by id	transferTypes/<id>	GET	Path variable id: the transfer type numeric identifier	Object: id: The internal, numerical identifier name: The transfer type name from: Object representing the account type. Contains the following properties: id: The internal, numerical identifier name: The account type name currency: Object representing the account currency. Contains the following properties: id: The internal, numerical identifier name: The currency name symbol: The currency symbol to: Same object as from
Search transfer types	transferTypes	GET	Query parameters: destination: Payment receiver. May be one of the following strings: MEMBER: Searches transfer types to other members. This is the default. SYSTEM: Searches transfer types to system accounts. toMemberId: Internal identifier of the destination member. Either this or toMemberPrincipal are required if destination is MEMBER. toMemberPrincipal: Principal (username, custom field, email, etc, as configured on the rest channel) of the destination member. Either this or toMemberId are required if destination is MEMBER. fromAccountId: Returns transfer types only from the specified account. Optional. currencyId: Returns transfer types only with the specified currency, getting the currency by id. Optional. currencySymbol: Returns transfer types only with the specified currency, getting the currency by symbol. Optional.	Array of the same objects as get transfer type by id

Payments

Allows making payments from the authenticated user to other members or to system accounts. To make a payment, a transfer type is always required. To be used here, the transfer type must allow the rest channel. When no transferTypeId is provided, it is possible to pass a currency id, using the first transfer type available for that currency. If neither transfer type nor currency are provided, the first available transfer type is used, prioritizing the default account.

When performing payments, the following error codes can be generated:

NOT_ENOUGH_FUNDS: Attempt to perform a payment without having enough funds.
MAX_AMOUNT_PER_DAY_EXCEEDED: Payment cannot be performed because the maximum allowed amount per day was exceeded.
UPPER_CREDIT_LIMIT_REACHED: Payment cannot be performed because the receiving account would exceed the maximum allowed balance.

Service	URI	HTTP method	Input	Result
Performs a validation payment from the authenticated member to another member returning crucial information needed to confirm the payment.	payments/memberPayment	POST	Request body: Object with the following properties: transactionPassword: The transaction password, which might be needed to complete the payment. Whether this is needed depends on the group settings (if the member group uses transaction password) and the REST channel configuration, where only used if credentials is 'Default' (login password + transaction password) toMemberId: Internal identifier for the destination member. Either this or toMemberPrincipal are required. toMemberPrincipal: Principal (username, e-mail, custom field, etc, as configured on the rest channel) for the destination member. Either this or toMemberId are required. amount: Numerical amount for the payment. Required. transferTypeId: Internal identifier for payment transfer type. Optional. currencyId: Internal identifier for payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. currencySymbol: The symbol for the payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. installments: Number of installments for this payment. Optional. If empty, will be assumed 1, and processed directly. The interval between installments is one month. firstInstallmentDate: ISO 8601 formatted date for the first installment. Optional. If using multiple installments and the first date was not informed, the first installment will be immediately processed. description: Payment description. Optional. Defaults to the transfer type description. customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id possibleValueId: The custom field possible value id value: The custom field value hidden: A boolean flag indicating whether the field value is hidden The field of a custom field value can be identified passing the internal name (internalName) or field id (fieldId). If the value of a custom field value is an enumerated value it is sufficient to pass the possible value id (possibleValueId), or the enumerated string value in the value parameter.	Object with the following properties: fromMember: Same object as load member by id toMember: Same object as load member by id wouldRequireAuthorization: Boolean flag indicating if the payment would require authorization unitsPattern (deprecated): String value containing the units pattern finalAmount: Numeric. The final payment amount considering fees. formattedFinalAmount: String. The formatted final payment amount considering fees. fees: The applicable payment fees, an array of objects containing the following information: name: name of the fee amount: numeric amount of the fee formattedAmount: formatted amount of the fee transferType: Same object as load transfer type by id customValues: A map keyed by the name of the custom field and the corresponding string value as the value.
Perform a payment from the authenticated member to another member	payments/confirmMemberPayment	POST	Request body: Object with the following properties: transactionPassword: The transaction password, which might be needed to complete the payment. Whether this is needed depends on the group settings (if the member group uses transaction password) and the REST channel configuration, where only used if credentials is 'Default' (login password + transaction password) toMemberId: Internal identifier for the destination member. Either this or toMemberPrincipal are required. toMemberPrincipal: Principal (username, e-mail, custom field, etc, as configured on the rest channel) for the destination member. Either this or toMemberId are required. amount: Numerical amount for the payment. Required. transferTypeId: Internal identifier for payment transfer type. Optional. currencyId: Internal identifier for payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. currencySymbol: The symbol for the payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. installments: Number of installments for this payment. Optional. If empty, will be assumed 1, and processed directly. The interval between installments is one month. firstInstallmentDate: ISO 8601 formatted date for the first installment. Optional. If using multiple installments and the first date was not informed, the first installment will be immediately processed. description: Payment description. Optional. Defaults to the transfer type description. customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id possibleValueId: The custom field possible value id value: The custom field value hidden: A boolean flag indicating whether the field value is hidden The field of a custom field value can be identified passing the internal name (internalName) or field id (fieldId). If the value of a custom field value is an enumerated value it is sufficient to pass the possible value id (possibleValueId), or the enumerated string value in the value parameter.	Object with the following properties: id: The numerical identifier for the generated transfer (if not scheduled) or scheduled payment pending: Boolean flag indicating whether the payment is pending authorization in order to be processed
Performs a validation payment from the authenticated member to a system account returning crucial information needed to confirm the payment.	payments/systemPayment	POST	Request body: Object with the following properties: transactionPassword: The transaction password, which might be needed to complete the payment. Whether this is needed depends on the group settings (if the member group uses transaction password) and the REST channel configuration, where only used if credentials is 'Default' (login password + transaction password) amount: Numerical amount for the payment. Required. transferTypeId: Internal identifier for payment transfer type. Optional. currencyId: Internal identifier for payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. currencySymbol: The symbol for the payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. description: Payment description. Optional. Defaults to the transfer type description. customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id possibleValueId: The custom field possible value id value: The custom field value hidden: A boolean flag indicating whether the field value is hidden The field of a custom field value can be identified passing the internal name (internalName) or field id (fieldId). If the value of a custom field value is an enumerated value it is sufficient to pass the possible value id (possibleValueId), or the enumerated string value in the value parameter.	Object with the following properties: fromMember: Same object as load member by id wouldRequireAuthorization: Boolean flag indicating if the payment would require authorization unitsPattern (deprecated): String value containing the units pattern finalAmount: Numeric. The final payment amount considering fees. formattedFinalAmount: String. The formatted final payment amount considering fees. fees: The applicable payment fees, an array of objects containing the following information: name: name of the fee amount: numeric amount of the fee formattedAmount: formatted amount of the fee transferType: Same object as load transfer type by id customValues: A map keyed by the name of the custom field and the corresponding string value as the value.
Performs a payment from the authenticated member to a system account	payments/confirmSystemPayment	POST	Request body: Object with the following properties: transactionPassword: The transaction password, which might be needed to complete the payment. Whether this is needed depends on the group settings (if the member group uses transaction password) and the REST channel configuration, where only used if credentials is 'Default' (login password + transaction password) amount: Numerical amount for the payment. Required. transferTypeId: Internal identifier for payment transfer type. Optional. currencyId: Internal identifier for payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. currencySymbol: The symbol for the payment currency. Optional. If passing in a currency, use either currencyId or currencySymbol. description: Payment description. Optional. Defaults to the transfer type description. customValues: An array containing objects, each describing a custom field value, with the following properties: internalName: The custom field internal name fieldId: The custom field id possibleValueId: The custom field possible value id value: The custom field value hidden: A boolean flag indicating whether the field value is hidden The field of a custom field value can be identified passing the internal name (internalName) or field id (fieldId). If the value of a custom field value is an enumerated value it is sufficient to pass the possible value id (possibleValueId), or the enumerated string value in the value parameter.	Object with the following properties: id: The numerical identifier for the generated transfer pending: Boolean flag indicating whether the payment is pending authorization in order to be processed
Get the necessary information to prepare a payment	payments/paymentData	GET	Same parameters as search transfer types	Object with the following properties: transferTypes: A list of the same object as get transfer type by id accountsStatus: A map with the account type id as key and same object as get status for specific account as the value. toMember: Same object as load member by id. It is only returned when a destination member is specified in the request.

Payment custom fields

Allows getting information on payment custom fields

Service	URI	HTTP method	Input	Result
Get details of a custom field by id	paymentFields/<id>	GET	Path variable id: numeric identifier	Same object as member custom field
Get details of a custom field by internal name	paymentFields/name/<internalName>	GET	Path variable internalName: custom field internal name	Same object as member custom field
List all payment custom fields of a given transfer type	paymentFields/byTransferType/<id>	GET	Path variable id: the transfer type numeric identifier	Array of the same objects as member custom field.
List all payment custom fields used as search filters on an sepecific account history	paymentFields/forSearch/<id>	GET	Path variable id: the account id	Array of the same objects as member custom field.
List all payment custom fields used as search filters on the default account history	paymentFields/forSearch/default	GET	none	Array of the same objects as member custom field.
List all payment custom fields displayed on the account history results on an sepecific account	paymentFields/forList/<id>	GET	Path variable id: the account id	Array of the same objects as member custom field.
List all payment custom fields displayed on the account history results on the default account	paymentFields/forList/default	GET	none	Array of the same objects as member custom field.
List the possible values of an enumerated custom field, finding the custom field by id, optionally filtering by parent value id	paymentFields/<id>/possibleValues[/<parentId>]	GET	Path variable id: the desired custom field's id Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of the same objects as getting a member field's possible values.
List the possible values of an enumerated custom field, finding the custom field by internal name, optionally filtering by parent value id	paymentFields/name/<name>/possibleValues[/<parentId>]	GET	Path variable name: the desired custom field's internal name Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of the same objects as getting a member field's possible values.

Advertisement custom fields

Allows searching and getting data about advertisement custom fields

Service	URI	HTTP method	Input	Result
Get details of a custom field by id	adFields/<id>	GET	Path variable id: numeric identifier	Same object as member custom field
Get details of a custom field by internal name	adFields/name/<internalName>	GET	Path variable internalName: custom field internal name	Same object as member custom field
List all advertisement custom fields	adFields	GET	none	Array of the same objects as member custom field.
List all ad custom fields used as search filters	adFields/forSearch	GET	Path variable id: the account id	Array of the same objects as member custom field.
List the possible values of an enumerated custom field, finding the custom field by id, optionally filtering by parent value id	adFields/<id>/possibleValues[/<parentId>]	GET	Path variable id: the desired custom field's id Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of the same objects as getting a member field's possible values.
List the possible values of an enumerated custom field, finding the custom field by internal name, optionally filtering by parent value id	adFields/name/<name>/possibleValues[/<parentId>]	GET	Path variable name: the desired custom field's internal name Path variable parentId: optional numeric identifier of a possible value of the field's parent, to only get values belonging to that parent	Array of the same objects as getting a member field's possible values.

Advertisement categories

Allows searching and getting data about advertisement categories

Service	URI	HTTP method	Input	Result
Get details of an advertisement category	adCategories/<id>	GET	Path variable id: numeric identifier	Object with the following properties: id: The internal, numerical identifier name: The category name children: Array with the same category objects, for each child category.
Get all categories	adCategories	GET	none	Array of the same objects as get category by id

Service	URI	HTTP method	Input	Result
Get details of an advertisement by id	ads/<id>	GET	Path variable id: numeric identifier	Object with the following properties: id: The internal, numerical identifier category: Same object as getting a category by id searching: Indicates whether this ad is an offer (false) or demand (true) title: The advertisement title description: The advertisement description. May be HTML formatted or plain text. html: Boolean flag indicating whether the description is HTML formatted (true) or plain text (false) price: The (optional) price for this ad formattedPrice: The (optional) price for this ad, formatted according to Cyclos's settings currency: The price currency, same object as in account details. images: Array of the same objects as member images.
Search for advertisements	ads	GET	Query parameters: currentPage: Number indicating the current result page, starting with 0 (the default). pageSize: Amount of results returned. 10 by default, 100 max. searching: Boolean flag indicating whether to return offers (false) or demands (true). Defaults to false. categoryId: Numeric identifier for the advertisement category. keywords: String used to match the title, description, custom fields and owner fields, in a full-text search. initialPrice: Numeric price to filter advertisements with price greater or equals the given parameter. finalPrice: Numeric price to filter advertisements with price less or equals the given parameter. memberId: Numeric id for ad owner. memberPrincipal: Principal (username, e-mail, custom field, etc, as defined on the rest channel) for ad owner. memberGroupIds: Ids for member's group filter. beginDate: ISO 8601 formatted date for the publication start. endDate: ISO 8601 formatted date for the publication end. withImagesOnly: Boolean flag indicating whether to return only advertisements with images. showAdFields: Boolean flag indicating whether the ad custom fields will be filled-in on the returned objects. showMemberFields: Boolean flag indicating whether the owner member custom fields will be filled-in on the returned objects. memberCustomValue.<fieldInternalName>: Value for a member custom field. Only works if the given custom field is marked for ads search. In case the custom field has an enumerated type, the id of a possible value should be entered here. adCustomValue.<fieldInternalName>: Value for an advertisement custom field. Only works if the given custom field is marked for search. In case the custom field has an enumerated type, the id of a possible value should be entered here.	An Object containing the following properties: currentPage: Number indicating the actual returned page, starting with 0 totalCount: Number indicating the total count of matched results elements: Array containing the same objects as load ad by id, except that customValues will only be filled if showAdFields was requested with true, and the owner's customValues will only be filled if showMemberFields was requested with true.
Search for own advertisements, optionally returning expired or scheduled ads. Also, the objects returned contains more data, which are visible to the owner only.	ads/mine	GET	Query parameters: currentPage: Number indicating the current result page, starting with 0 (the default). pageSize: Amount of results returned. 10 by default, 100 max.	An Object containing the following properties: currentPage: Number indicating the actual returned page, starting with 0 totalCount: Number indicating the total count of matched results elements: Array containing object with all properties of those on load ad by id, plus: status: Contains the advertisement status. May be one of the following: ACTIVE: The advertisement is within the publication period. PERMANENT: The advertisement is marked for permanent. EXPIRED: The advertisement publication end is a past date. SCHEDULED: The advertisement publication start is a future date. publicationStart: The ISO 8601 formatted publication start date. formattedPublicationStart: The publication start date formatted according to Cyclos' settings. publicationEnd: The ISO 8601 formatted publication end date. formattedPublicationEnd: The publication end date formatted according to Cyclos' settings.