regify Provider-SDK

Starts the connect and returns a session secret and session identifier.

The returned provider-name is base64 encoded to avoid encoding issues.

The password is the sha1 hashcode of a string which is combined using the hashcodes of „password“ and the session secret „bhz43bhufcsa4“ (see connect function).
PHP:

All hashcodes are encoded in hexadecimal format and are represented in lowercase.

Logs off the current user and destroys the session.

We recommend to use this function and do not let the session time out.

sdk.php?f=logout
result: OK

Userdata-Dataset is encoded using JSON format, look into the userdata dataset for further information. If it is transferred in URL, the data must be encoded always using base64 (jb).

The result returns the UserID of the newly created user.

Function will fail with error 13 in case the UserName is already existing.

UserName is deprecated! It is strongly recommended to not set UserName. In this case, the UserName is identical to the main email address. Please use it only for special purposes.

To add a new user, the userdata dataset does not need to contain all possible values. But some values are absolutely mandatory:

PASSWORD, LASTNAME and MAILADDRESS
If any of those values is missing, an ERROR 15 will be triggered. All other values can be left out. In this case, the regify-provider will use the most common default values.

If no USERNAME is passed to the useradd function, the SDK will set username to the email address (which is the default anyway).

u=<userid>

jb=<json userdata dataset base64> or POST j=<json userdata>

sdk.php?f=userchange&u=1234&jb=eyJVc2VybmFtZSI6IlBhdHJp(…​)IjowfQ==
result: OK

userdata dataset is encoded using JSON format. If it is transferred in URL, the data must be encoded always using base64.

If you try to change the email address, ensure that the address is already assigned to this user.

If the user is authenticated, your data for REALNAME, TITLENAME, FIRSTNAME, LASTNAME and COMPANY will get ignored. You need to remove the authentication using userauthenticate first.

Group-Administrator is not allowed to set SENDINGALLOWEDUNTIL, MAXTRANSACTIONS and SUBPROVIDERID. If a Group-Administrator is trying to set user flags S, I, G, D, B, P, A, O, they will be ignored.

u=<userid> or

n=<username> or nb=<username base64>

u=<userid> or

n=<username> or nb=<username base64>

sdk.php?f=userget&u=1234
result: OK | { "USERID" : "1234","USERNAME" : "PatrickStar","CREATIONDATE" : "2008-02-18 23:44:02" (…​) }

u=<userid> or

n=<username> or nb=<username base64>

sdk.php?f=usercheck&u=1234
result: OK | 1234 | 1 | 0

parameters of invited person:
m=<email address> or mb=<email address base64>
p=<title> or pb=<title base64>
{fn=<first name> or fnb=<first name base64>}
ln=<last name> or lnb=<last name base64>
{un=<username> or unb=<username base64>}
{o=<organisation> or ob=<organisation base64>}
{mn=<mobile phone number> or mnb=<mobile phone number base64>}
{g=1}

parameters of inviting person:
{in=<invitationer full name> or inb=<invitationer full name base64>}
{io=<invitationer organisation name> or iob=<invitationer organisation name base64>}
{im=<invitationer email address> or imb=<invitationer email address base64>}
{ia=<invitationer auth-level>}

other parameters:
{c=<languagecode>}
{i=<invitation comment> or ib=<invitation comment base64>}
{q=<personal message> or qb=<personal message base64>}

Creates an invitation for the given user and returns the UserID of the new generated entry.

An email will be sent to the user with instructions about how to activate the account and obtain an account password.

You can add an optional invitation comment for individual use (i/ib). This comment will be inserted into the INVITATIONCOMMENT field of the invited user (table tbluser) and will not be visible to any people in the portal.

If you do not set the un/unb parameter, the username will get generated by first trying to set its value to same value as the email. If that fails then, it will be generated using first name and last name. If a given username already exists, the username will get extended using a number (this does not trigger an error!).

The optional parameter ia is only accepted, if in/inb and im/imb are given, too. Otherwise it will be ignored.

In order to be able to invite a person using in/inb, im/imb, io/iob or ia parameter, the currently loggend-in user needs to own the INVITING-USER right or the SUPER-USER right (administration). Otherwise, this function returns error 20.

The optional g parameter allows direct group association (if set != 0). For this to work, the inviting user has to own the SDK role "GROUP MASTER" and he needs to be assigned to a group. The invited user will then automatically get assigned to the same group like the currently regify account. This is independent of the given "parameters of inviting person" (like in/inb, im/imb, io/iob or ia). If the requirements are not given, this parameter triggers error 36.

sdk.php?f=userinvite&un=PatrickStar&m=patrick.star@bikinibottom.com&p=Mr.&fn=Patrick&ln=Star&c=DE&qb=SGkgUGF0cmljay4%3D
result: OK | 1235

After calling this method, the newly generated user is not activated. To activate the account, the invited user needs to klick the link in his invitation email. If mobile phone number is given and provider supports SMS, the SMS process is executed (user needs to enter SMS code after clicking a link).

The invitation comment is never shown to users. It allows technical classification or allocation of invited users.

{i=<filter string> or ib=<filter string base64>}
{l=<limit>}

Returns a short JSON encoded array with some reduced user information about all available users of this provider.

If you define the optional filter string, the function will only return users that match the filter string in their Username, RealName, Company or email address.

The optional limit parameter defines, if you like to get only a reduced amount of results (numeric from 1 to n). If used, the result returns the most recent n users (highest UserIDs) at first (descending order).

sdk.php?f=usergetlist&i=Crab
result: OK | JSONDataset

The returned group information is only a small subset containing GroupID, GroupName and GroupCode of the available groups.

The JSON array is build like this (one user):

PHP decoding example:

u=<userid> or
n=<username> or nb=<username base64>
{p=<password> or pb=<password base64>, needs super-user rights}

Generates a new user-password and sends this to the given user.

If the optional p/pb value is given (works only with super-user rights), it does not send a mail to the user.

Super-user can reset the password of every user on the provider.

The group-administrator can only reset the passwords of his group members.

sdk.php?f=usernewpassword&u=1234
result: OK → User gets email and standard behavior like he forgot the old one.

sdk.php?f=usernewpassword&u=1234&p=myPasswd
result: OK → User gets nothing, password is set to “myPasswd” directly.

user selection:
u=<userid> or n=<username> or nb=<username base64>

authentication parameters:
t=<auth-type>
l=<auth-level>
c=<comment> or cb=<comment base64>
r=<return information> or rb=<return information base64>

Authenticates the given user.

setting of your provider AUTHTRANSMITURL value in provider-settings).

strStatus may be „OK“ or an error with no unlock code.

Only a user with super-user rights can authenticate users.

sdk.php?f=userauthenticate&u=765&t=1&l=5&c=example&r=0049172987654321
result: OK |65784328765432876554

The strUnlockCode will get returned only in case the return information (r) is not set or sending failed. If r is set, the strUnlockCode normaly returns empty and the unlock code will get transmitted to the authenticated person directly using the return information (in most cases SMS, if the provider offers such). If transmission failed, the unlock-code gets returned even if r has been set. Thus, in every case you receive an unlock-code as result, the user has not received it and it’s your job to transmit the unlock-code to the desired user!

Setting an auth-level of 0 (zero) means to remove any authentication of this user. The user is no longer authenticated. Return information will get ignored.

u=<userid> or
n=<username> or nb=<username base64>
jb=<json usersettings dataset base64> or POST j=<json userdata>

Changes one or more settings of the given user. The settings-values need to get transferred in a JSON encoded usersettings dataset using jb or POST[j].
For possible values of usersettings refer to the usersettings dataset. You do not need to set/use all possible value. Values that are not given will remain the previous setting.
Some settings can only get set even for yourself only if you have SUPER-USER rights. Check userdata dataset table for details about the affected fields.

sdk.php?f=usersetsettings&u=1234&jb=eyJTRU5EUkVNSU5ERVJNQUlMIiA6IDB9
result: OK

Info: this example sets {"SENDREMINDERMAIL" : 0}

u=<userid> or
n=<username> or nb=<username base64>

sdk.php?f=usergetsettings&u=1234
result: OK |{"SENDREGISTEREDMAIL":0,"SENDRECEIPTMAIL":1…​

u=<userid> or
n=<username> or nb=<username base64>
m=<email addresses> or mb=<email addresses base64>
t=<type>

Assigns one or more email addresses to the email addresses of the given user-id or username. If an email address already exists, no error will get returned as it will be recognized and handled correctly.

To add multiple email addresses, divide them using semicolon or comma.

In case of an error, the result is error 14 followed by a list of the failed email addresses.

sdk.php?f=mailadd&u=1234&m=patrick@bikinibottom.com;patrick@crabs.org
result: OK

Parameter t allows two types of adding email addresses:
0 = User needs to confirm the address using a link in mail (mail will get generated)
1 = The email address will be activated directly (only SUPER-USER)

The email addresses must be in correct SMTP format without any additional extensions like „Patrick Star <patrick@crabs.org>“, which would trigger an error 14. In case of an error, the error-number will be followed by a list of the email addresses that failed (divided by semicolon).

If you use mb (b64 encoded email addresses), please encode the whole string of email addresses including divider (semicolon or comma).

u=<userid> or
n=<username> or nb=<username base64>

Returns a list of all assigned email addresses of the given user. The email addresses are separated by semicolon.

Email addresses that are not activated until now, will get returned in squared brackets.

sdk.php?f=mailget&u=1234
result: OK | parick@bikinibottom.com;[patrick@crabs.org]
This means, that patrick@crabs.org is not yet activated.

u=<userid> or
n=<username> or nb=<username base64>
m=<email addresses> or mb=<email addresses base64>

Allows to dissolve the assignment of an email address to a user. If you like to delete more than one email address, divide email addresses using semicolon (;) or comma.

sdk.php?f=maildelete&u=1234&m=patrick@crabs.org
result: OK

Please keep in mind, that deletion of an email address generates clearing-traffic. Upon this, please do not delete and re-assign email addresses to simply add one. Use mailadd function even if you do not know if the email address is already assigned or not. Already assigned email addresses will not trigger an error.

This function does not trigger an error if the email address is not available at all.

If you use mb (b64 encoded email addresses), please encode the whole string of email addresses including divider (semicolon or comma).

m=<email addresses> or mb=<email addresses base64>
{i=<internal only>}

Allows to dissolve the assignment of an email address to a regify-account in the worldwide regify-network. If you like to check more than one email address, divide email addresses using semicolon (;) or comma.

The function return strAssignedAddresses are the email addresses, that are assigned to the regify-network. The ones that are not assigned will not get returned. Multiple returned addresses are divided using semicolon.

If you set the optional i parameter to a value greater than 0 (eg 1), the function ignores the clearing and checks only the local provider-database (check only local accounts). The default is to check the clearing, too.

sdk.php?f=checkmailassignment&m=patrick@crabs.org,thaddeus@crabs.org
result: OK|thaddeus@crabs.org (Thaddeus already assigned to a regify-account)

If you use mb (b64 encoded email addresses), please encode the whole string of email addresses including divider (semicolon or comma).

jb=<json groupdata dataset base64> or POST[json groupdata]
{m=<sendmail 0|1>}

sdk.php?f=groupadd&jb=eyJVc2VybmFtZSI6IlBhdHJp(…​)IjowfQ==
result: OK | GroupID

See the groupdata dataset for parameter reference. The GROUPNAME and GROUPADMINID are mandatory. A given GROUPID and SUBPROVIDERID will be ignored. Missing values will get a default value (even for the GROUPCODE Value).

If you set the optional m parameter to 1, the system sends an email to the group administrator (defined by GROUPADMINID). This function uses template 19 to inform the group administrator about his group code and the current group values.

To add users to the newly generated Group, please use groupadduser function.

n=<groupname> or nb=<groupname base64> or
i=<groupid>

sdk.php?f=groupget&i=6
result: OK | JSONDataset

Returns all group information about the given group. This does not return the assigned users. For this information, please refer to groupgetusers function.
To get the users that are assigned to this group, please use groupgetusers.
Group-master users are only allowed to retrieve data of their own group.

n=<groupname> or nb=<groupname base64> or
i=<groupid>

sdk.php?f=groupdelete&i=6
result: OK | 5

Deleting a group terminates the group membership of all assigned users. They will remain with active regify accounts but will no longer stay professional members. All unassigned users are falling back to private membership. intAffected returns the number of members that have been unsassigned by this function.

This function does not send an email to the affected users (like groupremoveuser does).

n=<groupname> or nb=<groupname base64> or
i=<groupid>
jb=<json groupdata dataset base64> or POST[json userdata]
{p=<prevent mail>}

sdk.php?f=groupchange&i=6&jb=eyJVc2VybmFtZSI6IlBhdHJp(…​)IjowfQ==
result: OK | 5

The value intAffected is only greater 0, if some premium-date of users has been affected. This depends on the setting of the SETPREMIUMANYTIME provider-parameter and if the SENDINGALLOWEDUNTIL parameter has been set in this call (if not, returns allways 0).

If you reduce the amount of MAXACCOUNTS lower as the number of currently assigned users, the users with the lowest activity will get removed first.

If p is not set or 0, the affected users will get an email about removing them from the group.

Returns a short JSON encoded array with some reduced group information about all available groups of this provider.

If you define the optional filter string (i/ib), the function will only return groups that match the filter string in their GROUPNAME, GROUPCODE or SALESID.

sdk.php?f=groupgetlist&i=Crab
result: OK | JSONDataset

The returned group information is only a small subset containing GroupID, GroupName and GroupCode of the available groups.

The JSON array is build like this (one group):

PHP decoding example:

n=<groupname> or
nb=<groupname base64> or
i=<groupid>

sdk.php?f=groupgetusers&i=7
result: OK | JSONDataset

The returned user information is only a small subset containing USERID, USERNAME, REALNAME and main MAILADDRESS of the assigned users.

The JSON array is build like this (one user):

PHP decoding example:

Group-master users are only allowed to retrieve data of their own group.

n=<groupname> or nb=<groupname base64> or
i=<groupid>
u=<userid>
{p=<prevent mail>}

Adds the user (only userid allowed) to the given group (i, n or nb). The assigned user will receive an email (template 17).

If you set the optional p parameter to a value greater 0, the email will get suppressed (silent).

sdk.php?f=groupadduser&i=7&u=18
result: OK

If the maximum number of users in a group is already reached, this function returns error-code 19.

If the given user is already assigned to the given group, the function returns „OK“, too.

If SETPREMIUMANYTIME is TRUE, the premium-membership of the user will be the one of the group - no matter if it was previously a longer premium-period! If SETPREMIUMANYTIME is FALSE, a user will get the premium-length of the group only, if his actual premium-membership is shorter. If it is longer, this will remain untouched.

Group-master users are only allowed to add users having the same mail-domain as the group-master itself.

u=<userid>
{p=<prevent mail>}

Removes the user (only userid allowed) from a group. The unassigned user will receive an email (template 18).

If you set the optional p parameter to a value greater 0, the email will get suppressed (silent).

If the user has not been assigned to a group, the function will return error-code 12.

sdk.php?f=groupremoveuser&u=18&p=1
result: OK

Unassigned (removed) users will get GROUPID = NULL and SENDINGALLOWEDUNTIL to a date of yesterday. So they will remain private member.

Group-master users are only allowed to remove users from their own user-group.

sdk.php?f=gettransactionstate&t=9876543
result: 9|2010-11-28 14:32:03

Returns the state of one given transaction-id. The following return values are possible:

0 = error or not found
1 = not fetched (in reminder period)
2 = not fetched (reminder period overdue)
3 = not fetched (archived)
9 = fetched

Please use gettransactionstatearray function to speed up if you like to check the state of a larger number of transactions.

Returns the state of all given transaction-ids. The result is a JSON encoded array in transaction dataset format.

Please submit the transaction-ids to request seperated by a comma. Please encode this using base64 for the tb parameter or submit it by using POST (t).

Example:
"9876543,9876544" ⇒ OTg3NjU0Myw5ODc2NTQ0

sdk.php?f=gettransactionstatearray&t=9876543,9876544
result: jsonArray

Returns the state of all given transaction-ids in an array that consists of transaction dataset entrys.

If you use tb (b64 encoded transaction id’s), please encode the whole string of id’s including divider (comma).

{i=<filter> or ib=<filter base64>}
{ds=<date start> and de=<date end>}
{s=<state>}
{t=<type>}
{l=<limit>}

Returns the data of all transactions that match the filter and/or the date-range and/or the given state (numeric).
The result is returned using a JSON array that contains transaction dataset entry’s.
The filter sentence i or ib) will get checked against the subject and the recipient email address.

If you set ds, you also have to set de - and vice versa.

Using the optional l parameter (lowercase L), you can limit the number of results. As the result is sorted with the newest transactions at first, you always get the newest transactions on top.

Possible state (s) values are only:
0 = not fetched
1 = fetched

Possible transaction types (t) are:
M = regimail
P = regipay
A = regibill premium
B = regibill standard
C = regichat protocols (deprecated! handle like regimail)
X = regibox invitations

sdk.php?f=gettransactionlist&i=patrick
result: JSON array with all transactions that match the word 'patrick'

If you do not enter a time for ds or de, please keep in mind that this means 00:00:00 as time. So „2010-09-22“ means „2010-09-22 00:00:00“. Used as de, this will not display any transaction that has been started on 22. September.

You can combine filter, date and state values together in one query (AND).

sdk.php?f=sqlget&sb=U0VMRUNUIFVzZXJuYW1lIEZST00gdGJsdXNlciBXSEVSRSBVc2VySUQ9Nw==
result: OK | JSONDataset

This function allows only queries that begin with „SELECT “. It will not work if you use any keywords like UPDATE, DELETE etc. to prevent data curruption and missuses. In this case, the function will return error-code 12. Please have a look into your logfile to get more information about this error.

This function encodes every returned value as string, even if it is only numeric. Upon this, a typical result for a select like

may return a result like this (remark the SUBPROVIDERID returned as string):