REST Web services

From Complete Cyclos documentation wiki
Jump to: navigation, search

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:
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:
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:

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.


Advertisements

Allows searching and getting data about advertisements

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.

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.


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